fix: make web file values opaque

Author: Error-Zhang

docs/compiler-architecture.md

@@ -217,7 +217,8 @@ for `match`; an asserted binding shape fails immediately.
   contextual project-editor seams;
   extensions declare opaque primitive types and their parent relations through
   the generic analysis contract, so Core assignability contains no Web type
-  names;
+  names; primitive members are read-only unless their owning extension
+  explicitly marks a field writable;
   loading lexical keywords alone can never silently activate Web semantics.
   Its `framework-host` subpath is a platform-neutral tooling ABI containing
   only protocol types and a version constant; it does not implement HTML,

docs/web-api.md

@@ -483,8 +483,9 @@ if selected.size > 0:
 ```
 
 `pick` uses the native file-input path supported by Chromium, Firefox, and
-WebKit. It returns stable VelarScript file records with `name`, `size`, `type`, and
-`modified`; only records returned by `pick` may be read with `readText` or
+WebKit. It returns `List<File>`, where opaque `File` values expose read-only
+`name`, `size`, `type`, and `modified` metadata; only values returned by `pick`
+may be read with `readText` or
 `readDataUrl` or attached to `velar/http.formBody`. Picker options are a
 data-only `accept` string/`multiple` bool record. `download` accepts actual text
 for its name, data, and MIME type. Invalid options, forged file records, and
@@ -497,7 +498,7 @@ persistent file handles, and the File System Access API are deliberately not
 part of Web API 0.10.
 
 Returned file names/MIME types, sizes, and modification times are validated
-before an opaque record is registered. Invalid native picker results reject
+before an opaque `File` is registered. Invalid native picker results reject
 the Promise instead of escaping an event callback or leaving it pending.
 `readText` and `readDataUrl` also verify the asynchronous reader result and its
 maximum encoded expansion before returning a string.

packages/compiler/src/analyzer.ts

@@ -253,6 +253,14 @@ const coreGlobalGuidance = new Map([
   ["String", "Use str(value) instead of the JavaScript String global"],
 ]);
 
+export function isCorePrimitiveName(name: string): boolean {
+  return corePrimitiveNames.has(name);
+}
+
+export function isCoreReservedBinding(name: string): boolean {
+  return reservedBindings.has(name);
+}
+
 export class Analyzer implements TypeEnvironment {
   protected readonly diagnostics: Diagnostic[] = [];
   private readonly scopes: Map<string, Binding>[] = [new Map()];
@@ -341,6 +349,7 @@ export class Analyzer implements TypeEnvironment {
   private callableOriginChanged = false;
   private readonly primitiveNames = new Set(corePrimitiveNames);
   private readonly primitiveParents = new Map<string, Set<string>>();
+  private readonly primitiveMutableFields = new Map<string, Set<string>>();
   private readonly extensionGlobals = new Map<string, ValueType>();
   private readonly extensionReservedBindings = new Set<string>();
   private readonly globalGuidance = new Map(coreGlobalGuidance);
@@ -383,6 +392,11 @@ export class Analyzer implements TypeEnvironment {
         for (const parent of parents) collected.add(parent);
         this.primitiveParents.set(name, collected);
       }
+      for (const [name, fields] of extension.primitiveMutableFields ?? []) {
+        const collected = this.primitiveMutableFields.get(name) ?? new Set<string>();
+        for (const field of fields) collected.add(field);
+        this.primitiveMutableFields.set(name, collected);
+      }
       for (const [name, type] of extension.globals ?? []) this.extensionGlobals.set(name, type);
       for (const name of extension.reservedBindings ?? []) this.extensionReservedBindings.add(name);
       for (const [name, guidance] of extension.globalGuidance ?? []) this.globalGuidance.set(name, guidance);
@@ -3387,6 +3401,11 @@ export class Analyzer implements TypeEnvironment {
       } else if (owner.kind === "object" && owner.readonlyFields?.has(statement.target.property)) {
         this.diagnostics.push(diagnostic("VEL3002", `Cannot assign to read-only field '${statement.target.property}'`, statement.target.span));
         targetWritable = false;
+      } else if (owner.kind === "named" && this.primitiveNames.has(owner.name)
+        && this.fieldsOf(owner.identity ?? owner.name)?.has(statement.target.property)
+        && !this.primitiveFieldWritable(owner.name, statement.target.property)) {
+        this.diagnostics.push(diagnostic("VEL3002", `Cannot assign to read-only member '${statement.target.property}'`, statement.target.span));
+        targetWritable = false;
       } else if (owner.kind === "object" && owner.optionalFields?.has(statement.target.property)) {
         targetType = owner.fields.get(statement.target.property) ?? targetType;
       }
@@ -3444,6 +3463,19 @@ export class Analyzer implements TypeEnvironment {
     }
   }
 
+  private primitiveFieldWritable(name: string, field: string): boolean {
+    const pending = [name];
+    const visited = new Set<string>();
+    while (pending.length > 0) {
+      const current = pending.pop()!;
+      if (visited.has(current)) continue;
+      visited.add(current);
+      if (this.primitiveMutableFields.get(current)?.has(field)) return true;
+      for (const parent of this.primitiveParents.get(current) ?? []) pending.push(parent);
+    }
+    return false;
+  }
+
   protected inferExpression(expression: Expression, contextualType: ValueType = unknownType): ValueType {
     const type = this.inferExpressionType(expression, contextualType);
     this.inferredExpressionTypes.set(spanIdentity(expression.span), type);

packages/compiler/src/extension.ts

@@ -74,6 +74,7 @@ export interface CompilerLexicalScanResult {
 export interface CompilerAnalysisExtension {
   readonly primitiveTypes?: ReadonlySet<string>;
   readonly primitiveParents?: ReadonlyMap<string, ReadonlySet<string>>;
+  readonly primitiveMutableFields?: ReadonlyMap<string, ReadonlySet<string>>;
   readonly globals?: ReadonlyMap<string, ValueType>;
   readonly reservedBindings?: ReadonlySet<string>;
   readonly globalGuidance?: ReadonlyMap<string, string>;

packages/compiler/src/index.ts

@@ -1,4 +1,4 @@
-import { Analyzer, type AnalysisContext, type ClassInfo } from "./analyzer.ts";
+import { Analyzer, isCorePrimitiveName, isCoreReservedBinding, type AnalysisContext, type ClassInfo } from "./analyzer.ts";
 import type { BindingPattern, Expression, FunctionDeclaration, MatchPattern, Program, Statement, TypeReference } from "./ast.ts";
 import { diagnostic, type Diagnostic } from "./diagnostic.ts";
 import { JavaScriptEmitter } from "./emitter.ts";
@@ -213,6 +213,8 @@ function parseModule(text: string, path: string, extensions: readonly CompilerEx
 function normalizedExtensions(extensions: readonly CompilerExtension[]): readonly CompilerExtension[] {
   const seen = new Set<string>();
   const capabilities = new Set<string>();
+  const primitiveOwners = new Map<string, string>();
+  const globalOwners = new Map<string, string>();
   for (const extension of extensions) {
     if (!extension.id || seen.has(extension.id)) throw new Error(`Compiler extension '${extension.id}' is invalid or duplicated`);
     seen.add(extension.id);
@@ -222,7 +224,56 @@ function normalizedExtensions(extensions: readonly CompilerExtension[]): readonl
       }
       capabilities.add(capability);
     }
+    for (const name of extension.analysis?.primitiveTypes ?? []) {
+      const owner = primitiveOwners.get(name);
+      if (isCorePrimitiveName(name)) throw new Error(`Compiler extension '${extension.id}' cannot replace Core primitive '${name}'`);
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name) || owner) {
+        throw new Error(`Compiler primitive '${name}' is invalid or has more than one owner${owner ? ` (${owner}, ${extension.id})` : ""}`);
+      }
+      primitiveOwners.set(name, extension.id);
+    }
+    for (const name of extension.analysis?.globals?.keys() ?? []) {
+      if (isCoreReservedBinding(name)) throw new Error(`Compiler extension '${extension.id}' cannot replace reserved Core binding '${name}'`);
+      const owner = globalOwners.get(name);
+      if (owner) throw new Error(`Compiler global '${name}' has more than one owner (${owner}, ${extension.id})`);
+      globalOwners.set(name, extension.id);
+    }
+  }
+
+  const parents = new Map<string, Set<string>>();
+  for (const extension of extensions) {
+    for (const [name, values] of extension.analysis?.primitiveParents ?? []) {
+      if (primitiveOwners.get(name) !== extension.id) {
+        throw new Error(`Compiler extension '${extension.id}' cannot define parents for primitive '${name}' that it does not own`);
+      }
+      const collected = parents.get(name) ?? new Set<string>();
+      for (const parent of values) {
+        if (!primitiveOwners.has(parent)) throw new Error(`Compiler primitive '${name}' has unknown parent '${parent}'`);
+        collected.add(parent);
+      }
+      parents.set(name, collected);
+    }
+    for (const [name, fields] of extension.analysis?.primitiveMutableFields ?? []) {
+      if (primitiveOwners.get(name) !== extension.id) {
+        throw new Error(`Compiler extension '${extension.id}' cannot make fields writable on primitive '${name}' that it does not own`);
+      }
+      for (const field of fields) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(field)) throw new Error(`Compiler primitive '${name}' has invalid writable field '${field}'`);
+      }
+    }
   }
+
+  const completed = new Set<string>();
+  const active = new Set<string>();
+  const visit = (name: string): void => {
+    if (completed.has(name)) return;
+    if (active.has(name)) throw new Error(`Compiler primitive inheritance contains a cycle at '${name}'`);
+    active.add(name);
+    for (const parent of parents.get(name) ?? []) visit(parent);
+    active.delete(name);
+    completed.add(name);
+  };
+  for (const name of primitiveOwners.keys()) visit(name);
   return extensions;
 }
 

packages/web/src/analyzer.ts

@@ -1021,6 +1021,7 @@ function webTypeFields(name: string): ReadonlyMap<string, ValueType> | null {
   if (name === "PointerEvent") return new Map([...eventFields(), ["pointerId", numberType], ["pointerType", stringType], ["pressure", numberType], ["button", numberType], ["buttons", numberType], ["clientX", numberType], ["clientY", numberType], ["movementX", numberType], ["movementY", numberType], ["altKey", boolType], ["ctrlKey", boolType], ["metaKey", boolType], ["shiftKey", boolType]]);
   if (name === "InputEvent") return new Map([...eventFields(), ["data", optionalOf(stringType)], ["inputType", stringType], ["isComposing", boolType]]);
   if (name === "Blob") return new Map();
+  if (name === "File") return new Map([["name", stringType], ["size", numberType], ["type", stringType], ["modified", numberType]]);
   if (name === "Element" || name === "InputElement" || name === "CanvasElement" || name === "DialogElement") {
     const fields = new Map<string, ValueType>([["focus", functionType([], [], nullType)], ["remove", functionType([], [], nullType)]]);
     if (name === "InputElement") { fields.set("value", stringType); fields.set("checked", boolType); }

packages/web/src/compiler.ts

@@ -86,7 +86,7 @@ const cleanupType = namedFunction([], [], nullType);
 const arrayString: ValueType = { kind: "list", element: stringType };
 const mapString = (value: ValueType): ValueType => ({ kind: "map", key: stringType, value });
 const webElementType: ValueType = { kind: "union", members: [elementType, inputElementType, canvasElementType, dialogElementType] };
-const fileType = object({ name: stringType, size: numberType, type: stringType, modified: numberType });
+const fileType: ValueType = { kind: "named", name: "File" };
 const fileArrayType: ValueType = { kind: "list", element: fileType };
 const formBodyType = object({
   field: namedFunction(["name", "value"], [stringType, stringType], nullType),
@@ -420,7 +420,7 @@ export const velarCompilerExtension: CompilerExtension = Object.freeze({
   semantic: velarWebSemanticExtension,
   inspection: velarWebInspectionExtension,
   analysis: Object.freeze({
-    primitiveTypes: new Set(["WebNode", "Element", "InputElement", "CanvasElement", "DialogElement", "Blob", "Event", "KeyboardEvent", "PointerEvent", "InputEvent", "Look", "Length", "Percentage", "Color", "Duration", "Angle", "Opacity", "Border", "Shadow", "Image", "Track", "TrackList", "Transition", "Spacing"]),
+    primitiveTypes: new Set(["WebNode", "Element", "InputElement", "CanvasElement", "DialogElement", "Blob", "File", "Event", "KeyboardEvent", "PointerEvent", "InputEvent", "Look", "Length", "Percentage", "Color", "Duration", "Angle", "Opacity", "Border", "Shadow", "Image", "Track", "TrackList", "Transition", "Spacing"]),
     primitiveParents: new Map([
       ["InputElement", new Set(["Element"])],
       ["CanvasElement", new Set(["Element"])],
@@ -429,6 +429,10 @@ export const velarCompilerExtension: CompilerExtension = Object.freeze({
       ["PointerEvent", new Set(["Event"])],
       ["InputEvent", new Set(["Event"])],
     ]),
+    primitiveMutableFields: new Map([
+      ["InputElement", new Set(["value", "checked"])],
+      ["CanvasElement", new Set(["width", "height"])],
+    ]),
     globals: webGlobals,
     reservedBindings: new Set(["mount", "tick"]),
     globalGuidance: new Map([
@@ -461,6 +465,7 @@ export const velarCompilerExtension: CompilerExtension = Object.freeze({
       CanvasElement: "A native canvas reference obtained through JSX `ref`.",
       DialogElement: "A native dialog reference obtained from `<dialog ref={value}>` and operated through `velar/browser`.",
       Blob: "An opaque binary HTTP body returned by `blob()` and accepted by HTTP request bodies.",
+      File: "An opaque selected file returned by `velar/files.pick()` with checked read-only metadata.",
       Event: "A restricted Web event value exposed to VelarScript event handlers.",
       Look: "A typed, composable Web appearance value applied through JSX look={...}.",
     }),

packages/web/src/emitter.ts

@@ -41,6 +41,15 @@ interface LookRule {
   readonly staticAtoms: readonly LookStaticAtom[];
 }
 
+const FILE_TYPE_RUNTIME = String.raw`
+function __velarFileTypeIs(value) {
+  const descriptor = Object.getOwnPropertyDescriptor(globalThis, Symbol.for("velar.file.registry.v1"));
+  if (!descriptor || !("value" in descriptor) || descriptor.configurable || descriptor.enumerable || descriptor.writable) return false;
+  try { return WeakMap.prototype.has.call(descriptor.value, value); }
+  catch { return false; }
+}
+`.trimStart();
+
 export class WebJavaScriptEmitter extends JavaScriptEmitter {
   private readonly reactive = new Map<string, "state" | "computed">();
   private currentScope: string | null = null;
@@ -49,6 +58,7 @@ export class WebJavaScriptEmitter extends JavaScriptEmitter {
   private cssOutput = "";
   private cssSegments: CompilerStyleSegments = { before: "", controlled: "", after: "" };
   private webOutput = false;
+  private needsFileTypeHelper = false;
   private jsxId = 0;
 
   constructor(
@@ -66,6 +76,7 @@ export class WebJavaScriptEmitter extends JavaScriptEmitter {
     for (const [name, kind] of this.hints.reactiveBindings) this.reactive.set(name, kind);
     this.prepareLooks(program);
     this.webOutput = containsWebSyntax(program);
+    this.needsFileTypeHelper = false;
     return super.emit(program);
   }
 
@@ -93,12 +104,19 @@ export class WebJavaScriptEmitter extends JavaScriptEmitter {
         return `((typeof HTMLInputElement !== "undefined" && ${value} instanceof HTMLInputElement) || (typeof HTMLSelectElement !== "undefined" && ${value} instanceof HTMLSelectElement) || (typeof HTMLTextAreaElement !== "undefined" && ${value} instanceof HTMLTextAreaElement))`;
       }
       if (type.name === "Blob") return `(typeof Blob !== "undefined" && ${value} instanceof Blob)`;
+      if (type.name === "File") {
+        this.needsFileTypeHelper = true;
+        return `__velarFileTypeIs(${value})`;
+      }
     }
     return super.emitTypeCheck(type, value, state);
   }
 
   protected override additionalHelpers(program: Program): readonly string[] {
-    return this.webOutput ? [WEB_RUNTIME] : [];
+    return [
+      ...(this.webOutput ? [WEB_RUNTIME] : []),
+      ...(this.needsFileTypeHelper ? [FILE_TYPE_RUNTIME] : []),
+    ];
   }
 
   protected override includesErrorNormalizationRuntime(): boolean {

packages/web/src/runtime.ts

@@ -19,6 +19,23 @@ function __velarInvokeOwnedCallback(callback, arguments_, phase, detail) {
 }
 `.trimStart();
 
+const fileRegistryRuntime = String.raw`
+const nativeFilesKey = Symbol.for("velar.file.registry.v1");
+const nativeFiles = (() => {
+  const descriptor = Object.getOwnPropertyDescriptor(globalThis, nativeFilesKey);
+  if (descriptor) {
+    if (!("value" in descriptor)) throw new TypeError("VelarScript file registry cannot be an accessor");
+    if (descriptor.configurable || descriptor.enumerable || descriptor.writable) throw new TypeError("VelarScript file registry ownership is invalid");
+    try { WeakMap.prototype.has.call(descriptor.value, descriptor.value); }
+    catch { throw new TypeError("VelarScript file registry is invalid"); }
+    return descriptor.value;
+  }
+  const registry = new WeakMap();
+  Object.defineProperty(globalThis, nativeFilesKey, { value: registry, enumerable: false, configurable: false, writable: false });
+  return registry;
+})();
+`.trimStart();
+
 const strictJsonRuntime = String.raw`
 const __velarMaxJsonCodeUnits = 16 * 1024 * 1024;
 const __velarMaxJsonNodes = 1000000;
@@ -1017,8 +1034,7 @@ ${listRuntime}
 ${optionsRuntime}
 ${strictJsonRuntime}
 ${runtimeTypeRuntime}
-const nativeFilesKey = Symbol.for("velar.file.registry.v1");
-const nativeFiles = globalThis[nativeFilesKey] ??= new WeakMap();
+${fileRegistryRuntime}
 const formBodies = new WeakMap();
 
 function runtimeHttpType(Type) { return __velarRequireRuntimeType(Type, "HTTP parsing"); }
@@ -1088,7 +1104,7 @@ function fieldName(value) {
 }
 
 function nativeFile(value) {
-  const file = value && nativeFiles.get(value);
+  const file = value && WeakMap.prototype.get.call(nativeFiles, value);
   if (!(file instanceof File)) throw new TypeError("Form body files must come from velar/files pick()");
   return file;
 }
@@ -1588,8 +1604,7 @@ function requireDialog(value) { if (typeof HTMLDialogElement === "undefined" ||
 `.trimStart()],
   ["velar/files", String.raw`
 ${optionsRuntime}
-const nativeFilesKey = Symbol.for("velar.file.registry.v1");
-const nativeFiles = globalThis[nativeFilesKey] ??= new WeakMap();
+${fileRegistryRuntime}
 const defaultFileReadBytes = 16 * 1024 * 1024;
 const maxFileReadBytes = 64 * 1024 * 1024;
 function readLimit(value) {
@@ -1606,10 +1621,10 @@ function wrap(file) {
   if (!Number.isFinite(modified) || modified < 0) throw new TypeError("Selected file modified time must be a non-negative finite number");
   const value = { name, size, type, modified };
   Object.freeze(value);
-  nativeFiles.set(value, file);
+  WeakMap.prototype.set.call(nativeFiles, value, file);
   return value;
 }
-function native(file) { const value = nativeFiles.get(file); if (!value) throw new TypeError("Expected a file returned by velar/files"); return value; }
+function native(file) { const value = WeakMap.prototype.get.call(nativeFiles, file); if (!value) throw new TypeError("Expected a file returned by velar/files"); return value; }
 export function pick(options = {}) {
   options = __velarOptions(options, "File picker options", new Set(["accept", "multiple"]));
   const accept = options.accept == null ? "" : __velarString(options.accept, "File accept filter");