@vgai/editor 0.2.0

package/src/scene-ui-mode/scene-ui-palette-panel.tsx

@@ -0,0 +1,152 @@
+/**
+ * E1.a (spec-27 §7 E1 / §9 "UIEditor chrome, palette, … MIGRATE" row) — the
+ * UI-node creation palette, surfaced in the MAIN editor (`editor.html`) for
+ * whichever world's scene-UI child is currently live. Reuses `ui-editor/
+ * palette.tsx`'s `UIPalette` (the harness component) UNCHANGED — its only
+ * prop is `store: UIEditStore`, so pointing it at the SAME `UIEditStore`
+ * instance `edit-mode-authoring.ts`'s `buildUIChild` constructed for the open
+ * scene wires creation through the real undo timeline (`UIEditStore`'s
+ * constructor already calls `registerUndoAdapter(this)`) and the real
+ * `.vscn` autosave (`onCommit` → `EditorStore.setSceneUI`) for free — no new
+ * store, no new undo plumbing.
+ *
+ * Also carries the E1.c "instantiate a saved prefab" surface (§8 "Scene-UI
+ * extras: … prefabs"): a list of `.uiprefab.json` assets under `ui-prefabs/`
+ * with a one-click instantiate into the current selection (or the first
+ * root) — the SAME "target the selected container, else first root" rule
+ * `scene-ui-layer.ts`'s registry component-insert strip (`componentStrip`)
+ * uses: a selection that isn't a container falls straight through to the
+ * first root. This is NOT the palette's own `add()` (`ui-editor/palette.tsx`),
+ * which has an extra middle tier — a selection that isn't a container falls
+ * back to that selection's PARENT first, and only THEN to the first root.
+ * (The SAVE half of the prefab flow is the hierarchy context-menu item,
+ * `ui-prefab-hierarchy-menu.ts` + `ui-prefab-dialog-host.tsx`.)
+ *
+ * Renders nothing when no scene-UI child is installed (§3.1's install gate —
+ * a ui-less scene has nothing to author here yet; see `ui-hierarchy-menu.ts`'s
+ * "Add UI Canvas" action for how a scene gets its first one).
+ */
+
+import { useEffect, useState } from 'react';
+import type { UIAuthoringAdapter } from '../authoring/ui-authoring-adapter';
+import { Panel } from '../components/primitives/Panel';
+import { findNode } from '../ui-editor/node-ops';
+import { UIPalette } from '../ui-editor/palette';
+import { instantiateUIPrefab } from '../ui-editor/ui-prefab';
+import { useActiveSceneUIAdapter } from './active-scene-ui';
+import {
+  fetchUIPrefabFile,
+  listUIPrefabAssets,
+  UI_PREFAB_SAVED_EVENT,
+  type UIPrefabAssetEntry,
+} from './ui-prefab-io';
+
+/** Mirrors `ui-editor/palette.tsx`'s own unexported `isContainer` / the
+ *  identical set in `authoring/scene-ui-layer.ts` — an instantiated prefab
+ *  nests under the selected container, else the first root. */
+const CONTAINER_KINDS = new Set([
+  'canvas',
+  'box',
+  'grid',
+  'stack',
+  'scroll',
+  'panel',
+  'center',
+  'wrap',
+  'aspect',
+  'sizebox',
+  'tab',
+]);
+
+export function SceneUIPalettePanel(): React.ReactNode {
+  const adapter = useActiveSceneUIAdapter();
+  if (!adapter) return null;
+  return (
+    <Panel
+      name="UI Palette"
+      data-testid="scene-ui-palette-panel"
+      style={{ width: 200, borderRight: '1px solid #333', overflowY: 'auto' }}
+    >
+      <UIPalette store={adapter.uiStore} />
+      <ScenePrefabsSection adapter={adapter} />
+    </Panel>
+  );
+}
+
+function ScenePrefabsSection({ adapter }: { adapter: UIAuthoringAdapter }): React.ReactNode {
+  const [prefabs, setPrefabs] = useState<UIPrefabAssetEntry[]>([]);
+
+  useEffect(() => {
+    let cancelled = false;
+    const refresh = () => {
+      void listUIPrefabAssets().then((list) => {
+        if (!cancelled) setPrefabs(list);
+      });
+    };
+    refresh();
+    window.addEventListener(UI_PREFAB_SAVED_EVENT, refresh);
+    return () => {
+      cancelled = true;
+      window.removeEventListener(UI_PREFAB_SAVED_EVENT, refresh);
+    };
+  }, []);
+
+  const store = adapter.uiStore;
+
+  const instantiate = async (entry: UIPrefabAssetEntry): Promise<void> => {
+    const prefab = await fetchUIPrefabFile(entry.path);
+    if (!prefab) return;
+    const instance = instantiateUIPrefab(prefab);
+    const primary = store.primary;
+    const primaryLoc = primary ? findNode(store.roots, primary) : null;
+    const parentId =
+      primaryLoc && CONTAINER_KINDS.has(primaryLoc.node.kind)
+        ? primary!
+        : ((store.roots[0]?.id as string | undefined) ?? null);
+    if (parentId) store.addNodeValue(parentId, instance);
+  };
+
+  return (
+    <div data-testid="scene-ui-prefabs" style={{ padding: 8, fontFamily: 'monospace' }}>
+      <div
+        style={{
+          fontSize: 10,
+          textTransform: 'uppercase',
+          color: '#888',
+          margin: '4px 0',
+          letterSpacing: 0.5,
+        }}
+      >
+        Prefabs
+      </div>
+      {prefabs.length === 0 && (
+        <div style={{ color: '#666', fontSize: 10 }}>
+          none yet — right-click a node → "Save UI Node as Prefab..."
+        </div>
+      )}
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 4 }}>
+        {prefabs.map((entry) => (
+          <button
+            key={entry.path}
+            type="button"
+            data-testid={`ui-prefab-instantiate-${entry.name}`}
+            title={`instantiate ${entry.name}`}
+            onClick={() => void instantiate(entry)}
+            style={{
+              background: '#262626',
+              color: '#ccc',
+              border: '1px solid #3a3a3a',
+              borderRadius: 3,
+              padding: '3px 7px',
+              fontSize: 11,
+              cursor: 'pointer',
+              fontFamily: 'monospace',
+            }}
+          >
+            {entry.name}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/scene-ui-mode/scene-ui-timeline-tab.tsx

@@ -0,0 +1,29 @@
+/**
+ * E1.b (spec-27 §7 E1 / §9 "…, timeline, …" MIGRATE row) — the keyframe/dope-
+ * sheet editor (`ui-editor/timeline-panel.tsx`'s `UITimeline`, reused
+ * UNCHANGED) mounted as a dockable bottom-panel tab in the unified editor
+ * (`components/BottomPanel.tsx`), for the currently active scene-UI child.
+ *
+ * Shares the SAME `UIEditStore` (so keyframe/track/clip edits are undoable +
+ * autosaved through the exact path the palette/inspector use) AND the SAME
+ * `UIAnimationController` the design-time stage plays back against
+ * (`UIAuthoringAdapter.anim` — see that field's doc comment for why the
+ * stage and the timeline can't each own their own controller instance:
+ * scrubbing here must move the SAME preview the stage renders).
+ */
+
+import { UITimeline } from '../ui-editor/timeline-panel';
+import { useActiveSceneUIAdapter } from './active-scene-ui';
+
+export function SceneUITimelineTab(): React.ReactNode {
+  const adapter = useActiveSceneUIAdapter();
+  if (!adapter) {
+    return (
+      <div style={{ padding: 12, color: '#777', fontSize: 12, fontFamily: 'monospace' }}>
+        No scene-UI world is open in this project — right-click a scene root in the hierarchy and
+        choose "Add UI Canvas" to author one.
+      </div>
+    );
+  }
+  return <UITimeline store={adapter.uiStore} anim={adapter.anim} />;
+}

package/src/scene-ui-mode/ui-prefab-dialog-host.tsx

@@ -0,0 +1,74 @@
+/**
+ * E1.c (spec-27 §7 E1) — the "Save UI Node as Prefab..." dialog, mounted once
+ * (see `components/DefaultEditorLayout.tsx`) alongside the 3D
+ * `PrefabSaveDialog` it shares its component with (parameterized — `extension`/
+ * `defaultFolder`/`title`, see that file). Listens for
+ * `ui-prefab-hierarchy-menu.ts`'s `UI_SAVE_AS_PREFAB_EVENT`, extracts the
+ * chosen node from the ACTIVE scene-UI child's live tree at save time (not at
+ * event-dispatch time — the tree may have changed since the context-menu
+ * click), and writes a `.uiprefab.json` via `ui-prefab-io.ts`.
+ */
+
+import { useCallback, useEffect, useState } from 'react';
+import { PrefabSaveDialog } from '../components/PrefabSaveDialog';
+import { findNode } from '../ui-editor/node-ops';
+import { resolveActiveSceneUIAdapter } from './active-scene-ui';
+import { UI_SAVE_AS_PREFAB_EVENT, type UISaveAsPrefabDetail } from './ui-prefab-hierarchy-menu';
+import {
+  buildUIPrefabFile,
+  saveUIPrefabToServer,
+  UI_PREFAB_DIR,
+  UI_PREFAB_EXTENSION,
+  UI_PREFAB_SAVED_EVENT,
+} from './ui-prefab-io';
+
+/** `a-z0-9-` filename hint from a node's display name — purely cosmetic
+ *  (the folder/filename fields stay freely editable), mirrors the 3D dialog's
+ *  own `entity.name` default-name usage (`DefaultEditorLayout.tsx`). */
+function slugify(name: string): string {
+  const slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return slug || 'ui-prefab';
+}
+
+export function UIPrefabDialogHost(): React.ReactNode {
+  const [pending, setPending] = useState<UISaveAsPrefabDetail | null>(null);
+
+  useEffect(() => {
+    const handler = (e: Event) => {
+      setPending((e as CustomEvent<UISaveAsPrefabDetail>).detail);
+    };
+    window.addEventListener(UI_SAVE_AS_PREFAB_EVENT, handler);
+    return () => window.removeEventListener(UI_SAVE_AS_PREFAB_EVENT, handler);
+  }, []);
+
+  const handleSave = useCallback(
+    (relPath: string) => {
+      const detail = pending;
+      setPending(null);
+      if (!detail) return;
+      const adapter = resolveActiveSceneUIAdapter();
+      const loc = adapter ? findNode(adapter.uiStore.roots, detail.nodeId) : null;
+      if (!loc) return;
+      const prefab = buildUIPrefabFile(detail.name, loc.node);
+      void saveUIPrefabToServer(prefab, relPath).then((ok) => {
+        if (ok) window.dispatchEvent(new CustomEvent(UI_PREFAB_SAVED_EVENT));
+      });
+    },
+    [pending],
+  );
+
+  if (!pending) return null;
+  return (
+    <PrefabSaveDialog
+      defaultName={slugify(pending.name)}
+      extension={UI_PREFAB_EXTENSION}
+      defaultFolder={UI_PREFAB_DIR}
+      title="Save UI Node as Prefab"
+      onSave={handleSave}
+      onCancel={() => setPending(null)}
+    />
+  );
+}

package/src/scene-ui-mode/ui-prefab-hierarchy-menu.ts

@@ -0,0 +1,49 @@
+/**
+ * "Save UI Node as Prefab..." hierarchy context-menu item (E1.c, spec-27 §7
+ * E1) — the scene-UI counterpart of `authoring/first-party-hierarchy-menu.ts`'s
+ * 3D prefab Save-as-Prefab action, registered through the SAME permanent
+ * escape hatch (`hierarchy-menu-registry.ts`, C2-blessed): `GameHierarchy`
+ * (the contract-only shell) never learns a UI tree exists, it only renders
+ * whatever this registration contributes for a matched row.
+ *
+ * Scoped to a node the ACTIVE scene-UI child's `UIEditStore` actually owns
+ * (`resolveActiveSceneUIAdapter` + `findNode`) — never matches a 3D entity or
+ * a foreign ingest/boundary node, and never fires when no scene-UI child is
+ * installed at all.
+ */
+
+import { registerHierarchyMenuItems } from '../hierarchy-menu-registry';
+import { findNode } from '../ui-editor/node-ops';
+import { resolveActiveSceneUIAdapter } from './active-scene-ui';
+
+/** Dispatched (on `window`) when the user picks "Save UI Node as Prefab..." —
+ *  `scene-ui-mode/ui-prefab-dialog-host.tsx` is the one listener, mirroring
+ *  `first-party-hierarchy-menu.ts`'s `editor:save-as-prefab` convention. */
+export const UI_SAVE_AS_PREFAB_EVENT = 'editor:ui-save-as-prefab';
+
+export interface UISaveAsPrefabDetail {
+  readonly nodeId: string;
+  readonly name: string;
+}
+
+registerHierarchyMenuItems(
+  (ctx) => {
+    const adapter = resolveActiveSceneUIAdapter();
+    return !!adapter && !!findNode(adapter.uiStore.roots, ctx.nodeId);
+  },
+  (ctx) => {
+    const adapter = resolveActiveSceneUIAdapter();
+    const loc = adapter ? findNode(adapter.uiStore.roots, ctx.nodeId) : null;
+    if (!loc) return [];
+    return [
+      {
+        label: 'Save UI Node as Prefab...',
+        color: '#60a5fa',
+        action: () => {
+          const detail: UISaveAsPrefabDetail = { nodeId: ctx.nodeId, name: loc.node.name };
+          window.dispatchEvent(new CustomEvent(UI_SAVE_AS_PREFAB_EVENT, { detail }));
+        },
+      },
+    ];
+  },
+);

package/src/scene-ui-mode/ui-prefab-io.ts

@@ -0,0 +1,76 @@
+/**
+ * E1.c (spec-27 §7 E1 / §8 "Scene-UI extras: prefabs" / §9 `ui-prefab.ts`
+ * MIGRATE row) — the save/list/fetch I/O the pure `ui-editor/ui-prefab.ts`
+ * functions (`instantiateUIPrefab`, unit-tested, no UI surface) never got: the
+ * harness exposed `instantiateUIPrefab` on `window.__uiRuntime` for e2e/proof
+ * scripts only (`ui-editor/harness.tsx`) — no author-facing save/instantiate
+ * flow existed anywhere before this unit. Mirrors the 3D prefab I/O
+ * (`components/DefaultEditorLayout.tsx`'s `savePrefabToServer`/
+ * `fetchPrefabFile`) but for `.uiprefab.json` (`UIPrefabFileSchema`,
+ * `packages/engine/src/scene/schema/ui.ts:590`) under a sibling `ui-prefabs/`
+ * folder convention (the 3D convention is `prefabs/`, `PrefabSaveDialog.tsx`'s
+ * default folder).
+ */
+
+import type { UINode } from '@engine/scene/schema';
+import { type UIPrefabFile, UIPrefabFileSchema } from '@engine/scene/schema';
+import { listAssets, readProjectTextFile, saveFile } from '../editor-api';
+
+/** Default folder a UI prefab saves to / is listed from — sibling of the 3D
+ *  `prefabs/` convention, never mixed with it (different file schema). */
+export const UI_PREFAB_DIR = 'ui-prefabs';
+export const UI_PREFAB_EXTENSION = 'uiprefab.json';
+
+/** Validate a raw parsed JSON object as a `.uiprefab.json` file. Throws a
+ *  `ZodError` on an invalid shape — callers decide how to surface that. */
+export function parseUIPrefabFile(json: unknown): UIPrefabFile {
+  return UIPrefabFileSchema.parse(json);
+}
+
+/** Build a fresh (version 1) `UIPrefabFile` around a UI node subtree. The
+ *  node's OWN ids are kept as authored — `instantiateUIPrefab` (`ui-prefab.ts`)
+ *  is what regenerates fresh ids, at INSTANTIATE time, not save time. */
+export function buildUIPrefabFile(name: string, root: UINode): UIPrefabFile {
+  return { version: 1, name, root };
+}
+
+/** Save a `.uiprefab.json` to disk via the editor server API (same
+ *  storage-backend seam every other project file write uses). */
+export async function saveUIPrefabToServer(prefab: UIPrefabFile, path: string): Promise<boolean> {
+  return saveFile(path, JSON.stringify(prefab, null, 2));
+}
+
+/** Fetch + validate a `.uiprefab.json` for an instantiate action. `null` on a
+ *  missing file OR one that fails schema validation (never throws). */
+export async function fetchUIPrefabFile(path: string): Promise<UIPrefabFile | null> {
+  const text = await readProjectTextFile(path);
+  if (text === null) return null;
+  try {
+    return parseUIPrefabFile(JSON.parse(text));
+  } catch {
+    return null;
+  }
+}
+
+export interface UIPrefabAssetEntry {
+  /** Display name (filename minus the `.uiprefab.json` suffix). */
+  name: string;
+  /** Project-relative path, ready for `fetchUIPrefabFile`. */
+  path: string;
+}
+
+/** Every `.uiprefab.json` file in {@link UI_PREFAB_DIR} (empty array if the
+ *  folder doesn't exist yet — `listAssets` already degrades that way). */
+export async function listUIPrefabAssets(): Promise<UIPrefabAssetEntry[]> {
+  const entries = await listAssets('', UI_PREFAB_DIR);
+  return entries
+    .filter((e) => e.type === 'file' && e.name.endsWith(`.${UI_PREFAB_EXTENSION}`))
+    .map((e) => ({
+      name: e.name.slice(0, -(UI_PREFAB_EXTENSION.length + 1)),
+      path: `${UI_PREFAB_DIR}/${e.name}`,
+    }));
+}
+
+/** Dispatched after a UI prefab is successfully saved, so any open "instantiate"
+ *  picker (the palette's prefabs section) refreshes its list without a reopen. */
+export const UI_PREFAB_SAVED_EVENT = 'editor:ui-prefab-saved';

package/src/script-loader.ts

@@ -0,0 +1,143 @@
+/**
+ * Script loader — dynamically imports project scripts via Vite.
+ *
+ * When a project is open, Vite serves the project directory via /@fs/ paths
+ * (enabled by server.fs.allow in vite.config.ts). This module imports the
+ * project's main script entry point and extracts the setup function.
+ *
+ * W1 — editor parity (docs/R3F-FIRST-PARTY-DESIGN.md §1.A/§2 W1). The
+ * standalone path's `defaultThreeKindFactory`
+ * (`packages/engine/src/runtime/mount-game.ts:174-186`) already accepts a
+ * first-party entry module that exports EITHER a pre-built `adapter`
+ * (`GameAdapter`) OR a `setup` function, and only hard-errors when a module
+ * exports neither. This module used to lag that contract — it hard-threw on
+ * ANY module lacking `setup`, so an `adapter`-export entry that mounted fine
+ * standalone failed here. `ProjectScripts` now carries both as optional
+ * fields and `loadProjectScripts`/`reloadProjectScripts` error only when
+ * NEITHER is present, with a message mirroring
+ * `defaultThreeKindFactory`'s wording so the two paths fail identically.
+ */
+
+import type { GameAdapter } from '@engine/adapter';
+import type { GameComponentClass } from '@engine/ecs/game-component';
+import type { GameSetupFn } from '@engine/runtime/types';
+
+export interface ProjectScripts {
+  /** Present when the entry module exports a pre-built `GameAdapter` — the
+   *  same `mod.adapter` shape `defaultThreeKindFactory` prefers
+   *  (mount-game.ts:176). Optional: a project may instead export `setup`. */
+  adapter?: GameAdapter | undefined;
+  /** Present when the entry module exports a `setup()` function — the
+   *  long-standing first-party contract. Optional as of W1: a project may
+   *  instead export `adapter` (see above). At least one of `adapter`/`setup`
+   *  is always present on a successfully loaded `ProjectScripts` — callers
+   *  that only support `setup` (e.g. `resolveDefaultPixiAdapter`, which is
+   *  OUT of W1's scope — docs/R3F-FIRST-PARTY-DESIGN.md §0.1's kind-parity
+   *  matrix) must check for `undefined` explicitly rather than assume it. */
+  setup?: GameSetupFn | undefined;
+  components?: Record<string, GameComponentClass> | undefined;
+}
+
+/** Runtime shape a `GameAdapter` export must satisfy before either load
+ *  function will accept it in place of `setup` — mirrors `guardModuleShape`'s
+ *  check in `packages/editor/src/adapter-resolver.ts` (`{ module }` adapters):
+ *  a non-null object with a non-empty string `id` and a function `mount`.
+ *  Kept local (rather than imported) because `adapter-resolver.ts` already
+ *  imports FROM this module (`loadProjectScripts`) — importing back would be
+ *  circular. */
+function isGameAdapterShaped(candidate: unknown): candidate is GameAdapter {
+  if (candidate === null || typeof candidate !== 'object') return false;
+  const obj = candidate as Record<string, unknown>;
+  return (
+    typeof obj['id'] === 'string' && obj['id'].length > 0 && typeof obj['mount'] === 'function'
+  );
+}
+
+/**
+ * Extract `{ adapter?, setup?, components? }` from a dynamically imported
+ * entry module, throwing the shared "neither export" error (worded to match
+ * `defaultThreeKindFactory`'s own error — mount-game.ts:179-183) when the
+ * module satisfies neither contract. Shared by `loadProjectScripts` and
+ * `reloadProjectScripts` so the two functions can never drift apart on this
+ * check.
+ */
+function extractProjectScripts(
+  // biome-ignore lint/suspicious/noExplicitAny: a dynamically `import()`ed module's shape is unknown until checked
+  mod: any,
+  scriptEntry: string,
+): ProjectScripts {
+  const adapter = isGameAdapterShaped(mod?.adapter) ? (mod.adapter as GameAdapter) : undefined;
+  const setup = typeof mod?.setup === 'function' ? (mod.setup as GameSetupFn) : undefined;
+
+  if (!adapter && !setup) {
+    throw new Error(
+      `Project script at ${scriptEntry} exports neither \`adapter\` nor \`setup\` — every ` +
+        'first-party entry module exports at least one (see ' +
+        'packages/editor/template/src/scripts/main.ts).',
+    );
+  }
+
+  const components = mod.components as Record<string, GameComponentClass> | undefined;
+  loadedComponents = components ?? {};
+  return { adapter, setup, components };
+}
+
+/**
+ * The most recently loaded project component classes, keyed by class name.
+ * Populated by `loadProjectScripts`/`reloadProjectScripts` so non-play surfaces
+ * (e.g. the schema-driven inspector) can read a component's `static schema`
+ * without re-importing project code. Empty until the first load.
+ */
+let loadedComponents: Record<string, GameComponentClass> = {};
+
+/** Get the component classes from the most recent project script load. */
+export function getLoadedComponents(): Record<string, GameComponentClass> {
+  return loadedComponents;
+}
+
+/**
+ * Set the loaded component classes directly. Used by the browser build's
+ * play-mode path (`browser-project-scripts.ts`), which obtains components from
+ * the in-browser transpiled bundle rather than a dev-server import, but still
+ * wants inspector surfaces to read their `static schema`s via
+ * `getLoadedComponents()`.
+ */
+export function setLoadedComponents(components: Record<string, GameComponentClass>): void {
+  loadedComponents = components;
+}
+
+/**
+ * Load project scripts from the given project path.
+ *
+ * The project's entry point is `src/scripts/main.ts`, which must export
+ * EITHER (or both — the EDITOR prefers `setup`, which alone threads
+ * `editorPreview` + the firstParty HMR brand, see
+ * `resolveDefaultThreeAdapter`; standalone prefers `adapter`,
+ * mount-game.ts:176):
+ *   - adapter: GameAdapter — a pre-built adapter (W1, docs/R3F-FIRST-PARTY-
+ *     DESIGN.md §1.A — the same `mod.adapter` shape `defaultThreeKindFactory`
+ *     accepts standalone, mount-game.ts:176)
+ *   - setup(ctx: GameContext): Promise<GameCleanup>
+ */
+export async function loadProjectScripts(
+  projectPath: string,
+  scriptEntry = 'src/scripts/main.ts',
+): Promise<ProjectScripts> {
+  const modulePath = `/@fs/${projectPath}/${scriptEntry}`;
+  const mod = await import(/* @vite-ignore */ modulePath);
+  return extractProjectScripts(mod, scriptEntry);
+}
+
+/**
+ * Re-import project scripts with a cache-busting timestamp.
+ * Used by the HMR handler to pick up updated code without a full page reload.
+ * Same `adapter`-or-`setup` contract as `loadProjectScripts` above.
+ */
+export async function reloadProjectScripts(
+  projectPath: string,
+  scriptEntry = 'src/scripts/main.ts',
+): Promise<ProjectScripts> {
+  const modulePath = `/@fs/${projectPath}/${scriptEntry}?t=${Date.now()}`;
+  const mod = await import(/* @vite-ignore */ modulePath);
+  return extractProjectScripts(mod, scriptEntry);
+}

package/src/storage/fsa-storage.ts

@@ -0,0 +1,55 @@
+/**
+ * Browser `StorageBackend` over a real on-disk folder, via the File System
+ * Access API (`showDirectoryPicker()` → `FileSystemDirectoryHandle`).
+ *
+ * Unlike OPFS (sandboxed), this reads and writes the actual directory the user
+ * picked — so the in-browser editor can edit a project that also lives on disk /
+ * in git. Same handle API as OPFS, so all logic is inherited from
+ * `HandleStorage`; this subclass adds the read/write permission gate the FSA
+ * spec requires before touching a user-granted handle.
+ *
+ * Chromium-only today (Firefox/Safari lack `showDirectoryPicker`); callers fall
+ * back to `OpfsStorage` where it is unavailable.
+ */
+
+import { HandleStorage } from './handle-storage';
+
+/** Subset of the FSA permission API (not in older TS DOM libs). */
+interface PermissionedHandle {
+  queryPermission?(d: { mode: 'read' | 'readwrite' }): Promise<PermissionState>;
+  requestPermission?(d: { mode: 'read' | 'readwrite' }): Promise<PermissionState>;
+}
+
+export class FsaStorage extends HandleStorage {
+  readonly id = 'fsa';
+
+  private permission: Promise<void> | null = null;
+
+  constructor(private readonly handle: FileSystemDirectoryHandle) {
+    super();
+  }
+
+  protected async rootHandle(): Promise<FileSystemDirectoryHandle> {
+    await this.ensurePermission();
+    return this.handle;
+  }
+
+  /** Ensure read/write permission on the picked handle (prompts at most once). */
+  private ensurePermission(): Promise<void> {
+    if (!this.permission) {
+      this.permission = (async () => {
+        const h = this.handle as FileSystemDirectoryHandle & PermissionedHandle;
+        // A handle with no permission API is already usable as-is (e.g. OPFS).
+        if (!h.queryPermission && !h.requestPermission) return;
+        const opts = { mode: 'readwrite' } as const;
+        if ((await h.queryPermission?.(opts)) === 'granted') return;
+        if ((await h.requestPermission?.(opts)) === 'granted') return;
+        throw new Error('FsaStorage: read/write permission to the chosen folder was denied.');
+      })().catch((err) => {
+        this.permission = null; // allow a retry after a denial
+        throw err;
+      });
+    }
+    return this.permission;
+  }
+}