@unoverse-platform/studio 0.1.4 → 0.1.6

package/screens/TemplatesView.tsx

@@ -115,10 +115,22 @@ const VIEWPORTS: { id: string; label: string; w: number | null }[] = [
   { id: "full", label: "Full", w: null },
 ];
 
-export function TemplatesView({ theme: defaultTheme, themeName, org = "all" }: { theme: ResolvedTheme; themeName: string; org?: string }) {
-  // MOCK (default, offline) vs LIVE (real Gravity data plane). A fresh store per
-  // mode keeps the two paths from bleeding into each other.
-  const [live, setLive] = useState(false);
+export function TemplatesView({
+  theme: defaultTheme,
+  themeName,
+  org = "all",
+  defaultLive = false,
+}: {
+  theme: ResolvedTheme;
+  themeName: string;
+  org?: string;
+  /** Which mode the view opens in. Standalone Studio authors offline, so it stays MOCK;
+   *  inside Canvas the universe is right there and a real render is what you came for. */
+  defaultLive?: boolean;
+}) {
+  // MOCK (offline) vs LIVE (real data plane). A fresh store per mode keeps the two paths
+  // from bleeding into each other.
+  const [live, setLive] = useState(defaultLive);
   const [templates, setTemplates] = useState<Def[]>([]);
   const [components, setComponents] = useState<Def[]>([]);
   const [selected, setSelected] = usePersistentState<string | null>("wb:templates:selected", null);

package/screens/index.ts

@@ -24,3 +24,6 @@ export { stateActivation } from "./states";
 // its own screen (Canvas from MarketplaceView, local Studio from the node testing area),
 // so it is shared even though neither shares the screen around it.
 export { ConfigForm, defaultsFromSchema } from "./ConfigForm";
+// The source view renders only where the host grants source access, so it is exported
+// unconditionally and returns null in Canvas (docs/architecture/LOCAL_STUDIO.md).
+export { SourceView } from "./SourceView";

package/screens/source/FileTree.tsx

@@ -0,0 +1,131 @@
+/**
+ * THE FILE RAIL: what this definition is made of, as a tree.
+ *
+ * A component folder holds its envelope, a manifest, and `layouts/`, `states/` and
+ * `components/` partials, which is easily a dozen files. Opening all of them as tabs eats
+ * the width, pushes the actions off the edge and makes the list unreadable at exactly the
+ * moment it matters. A rail lists them in one narrow column and the editor keeps the rest.
+ *
+ * Folders group in the order a developer reads them: the envelope first, then the manifest,
+ * then the partial folders.
+ */
+import { useMemo } from "react";
+
+export interface SourceFile {
+  path: string;
+  rel: string;
+  writable: boolean;
+  reason?: "installed" | "outside-project" | "not-a-file";
+}
+
+const fileName = (rel: string) => rel.slice(rel.lastIndexOf("/") + 1);
+/** A layout's filename IS its state name. The name-sync rule is what makes this safe. */
+export const stateOf = (rel: string) => fileName(rel).replace(/\.(ya?ml|json)$/, "");
+
+/**
+ * Group by folder, root files first, folders in reading order.
+ *
+ * LAYOUTS FOLLOW THE STATE ORDER, not the alphabet. A component's faces are declared in
+ * order by its root `Switch on defaultState`, and that order is what the state control in
+ * the toolbar shows. Sorting the same set alphabetically here made the rail and the
+ * toolbar disagree about a sequence they both take from one place.
+ */
+function group(files: SourceFile[], layoutOrder: string[]): { dir: string; files: SourceFile[] }[] {
+  const byDir = new Map<string, SourceFile[]>();
+  for (const f of files) {
+    const i = f.rel.lastIndexOf("/");
+    const dir = i === -1 ? "" : f.rel.slice(0, i);
+    if (!byDir.has(dir)) byDir.set(dir, []);
+    byDir.get(dir)!.push(f);
+  }
+  const order = ["", "layouts", "states", "components", "blocks"];
+  const rank = (list: string[], name: string) => {
+    const i = list.indexOf(name);
+    return i === -1 ? list.length : i;
+  };
+  return [...byDir.entries()]
+    .sort(([a], [b]) => rank(order, a) - rank(order, b) || a.localeCompare(b))
+    .map(([dir, list]) => ({
+      dir,
+      files:
+        dir === "layouts" && layoutOrder.length
+          ? [...list].sort(
+              (x, y) =>
+                rank(layoutOrder, stateOf(x.rel)) - rank(layoutOrder, stateOf(y.rel)) ||
+                x.rel.localeCompare(y.rel),
+            )
+          : list,
+    }));
+}
+
+export function FileTree({
+  files,
+  active,
+  dirtyPaths,
+  accent,
+  layoutOrder = [],
+  liveState,
+  onPick,
+}: {
+  files: SourceFile[];
+  active: SourceFile | null;
+  /** Paths with unsaved edits, so the rail carries the same marker the editor does. */
+  dirtyPaths: Set<string>;
+  accent?: string;
+  /** The component's faces, in declared order. Layouts are listed to match. */
+  layoutOrder?: string[];
+  /** The view being rendered. Marked LIVE whether or not it is the file being read. */
+  liveState?: string;
+  onPick: (f: SourceFile) => void;
+}) {
+  const groups = useMemo(() => group(files, layoutOrder), [files, layoutOrder]);
+
+  /**
+   * NO TITLE AND NO BACK CONTROL. The item list beside this rail already shows what is
+   * selected and is how you leave, and the toolbar names it again. A third copy of the
+   * name buys nothing and costs a row at the top of every file list.
+   */
+  return (
+    <div className="flex w-44 shrink-0 flex-col overflow-y-auto border-r border-gray-800 bg-[#171c24] py-1">
+      {groups.map(({ dir, files: list }) => (
+        <div key={dir || "."} className="mb-1">
+          {dir && (
+            <div className="px-2 py-0.5 text-[10px] uppercase tracking-wider text-gray-600">{dir}</div>
+          )}
+          {list.map((f) => {
+            /**
+             * TWO FACTS, TWO MARKS.
+             *
+             * `open` is the file in the editor, and `live` is the view on the preview.
+             * They coincide only while you happen to be reading the layout being drawn,
+             * and one mark for both meant opening `manifest.yaml` erased any sign of what
+             * the preview was showing. Open is a neutral highlight; live keeps the accent
+             * and the word, wherever it is in the list.
+             */
+            const open = active?.path === f.path;
+            const live = dir === "layouts" && !!liveState && stateOf(f.rel) === liveState;
+            return (
+              <button
+                key={f.path}
+                onClick={() => onPick(f)}
+                title={f.path}
+                className={`flex w-full items-center gap-1.5 px-2 py-1 text-left text-[11px] ${
+                  open ? "bg-white/[0.09] text-gray-100" : "text-gray-400 hover:bg-white/5 hover:text-gray-200"
+                }`}
+                style={{
+                  ...(open ? { boxShadow: "inset 2px 0 0 #6b7280" } : {}),
+                  ...(live ? { color: accent ?? "#10b981" } : {}),
+                }}
+              >
+                <span className="min-w-0 flex-1 truncate">{fileName(f.rel)}</span>
+                {live && <span className="shrink-0 text-[9px] uppercase tracking-wide opacity-80">live</span>}
+                {dirtyPaths.has(f.path) && <span className="shrink-0 text-amber-400">●</span>}
+                {!f.writable && <span className="shrink-0 text-[9px] text-gray-600">RO</span>}
+              </button>
+            );
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}

package/screens/source/completion.ts

@@ -0,0 +1,152 @@
+/**
+ * INTELLISENSE for definitions.
+ *
+ * The vocabulary is CLOSED, so a completion list here is not a hint, it is the whole legal
+ * set: sixteen primitives, a fixed style key set, and token names instead of raw values. A
+ * developer who accepts a completion cannot write something the linter will reject, which
+ * is a stronger promise than a text editor's schema hints can make.
+ *
+ * The lists come from the host (`/local/vocabulary`), which reads them from the SAME
+ * library the linter enforces and from the project's OWN resolved theme. So the tokens
+ * offered are the developer's real tokens, and a new token appears in completion the moment
+ * it exists.
+ *
+ * WHAT DECIDES WHICH LIST. Definitions are YAML or JSON with a shallow, predictable shape,
+ * so the key being typed is enough: `type:` wants a primitive, a key inside `style:` wants
+ * a style key, `background:` wants a colour token, `gap:` wants a space step. The context
+ * is read from the current line and the enclosing block, not from a full parse, because a
+ * document mid-keystroke is usually not parseable at all.
+ */
+import type { CompletionContext, CompletionResult, Completion } from "@codemirror/autocomplete";
+import { EditorView, Decoration, type DecorationSet } from "@codemirror/view";
+import { StateField, type EditorState } from "@codemirror/state";
+
+/**
+ * HIDE THE `$schema` LINE.
+ *
+ * It exists for editors that need a schema pointer, and Studio is not one: it lints with
+ * the real rule library and completes from the actual vocabulary and the project's own
+ * tokens. So here it is noise in the worst position, the first line of every file, and its
+ * `../../../../` depth changes with where the file sits, which reads as a puzzle.
+ *
+ * HIDDEN, NOT REMOVED. The text stays in the document and is saved back untouched, so a
+ * developer's VS Code setup is unaffected. Line numbers keep counting it, so a lint finding
+ * on line 12 is still line 12 in any other editor.
+ */
+const schemaLine = /^\s*\$schema\s*:/;
+
+/** A block decoration has to come from a StateField; from a plugin CodeMirror throws. */
+const build = (state: EditorState): DecorationSet => {
+  const first = state.doc.line(1);
+  if (!schemaLine.test(first.text)) return Decoration.none;
+  return Decoration.set([Decoration.replace({ block: true }).range(first.from, first.to)]);
+};
+
+export const hideSchemaLine = StateField.define<DecorationSet>({
+  create: build,
+  update: (deco, tr) => (tr.docChanged ? build(tr.state) : deco),
+  provide: (f) => EditorView.decorations.from(f),
+});
+
+export interface Vocabulary {
+  primitives: string[];
+  styleKeys: string[];
+  conditionKeys: string[];
+  dimensionKeys: string[];
+  tokens: { color: string[]; space: string[]; font: string[]; lineHeight: string[]; radius: string[]; shadow: string[] };
+  atoms: string[];
+  components: string[];
+}
+
+/** Style keys whose value is a colour token. */
+const COLOR_KEYS = new Set(["background", "color", "border", "borderTop", "borderRight", "borderBottom", "borderLeft", "outline", "radial"]);
+
+const opt = (label: string, detail: string, type: string): Completion => ({ label, detail, type });
+
+/** The indent of a line, in spaces. Tabs are not used in definitions. */
+const indentOf = (line: string) => line.length - line.trimStart().length;
+
+/**
+ * Is the cursor inside a `style:` block?
+ *
+ * Walk backwards to the nearest line whose indent is less than this one and read its key.
+ * A `style:` ancestor at any depth counts, which is what makes a nested node's style block
+ * behave the same as a root one.
+ */
+function enclosingKey(lines: string[], row: number, indent: number): string | null {
+  for (let i = row - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const ind = indentOf(line);
+    if (ind < indent) {
+      const m = /^\s*-?\s*"?([A-Za-z_][\w.-]*)"?\s*:/.exec(line);
+      return m ? m[1] : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * The completion source.
+ *
+ * Returns null (rather than an empty list) wherever the vocabulary has nothing to say, so
+ * the editor falls through to its own word completion instead of showing an empty popup.
+ */
+export function unoverseCompletion(getVocab: () => Vocabulary | null) {
+  return (ctx: CompletionContext): CompletionResult | null => {
+    const vocab = getVocab();
+    if (!vocab) return null;
+
+    const line = ctx.state.doc.lineAt(ctx.pos);
+    const upto = line.text.slice(0, ctx.pos - line.from);
+    const doc = ctx.state.doc;
+    const lines: string[] = [];
+    for (let i = 1; i <= doc.lines; i++) lines.push(doc.line(i).text);
+    const row = line.number - 1;
+
+    // ── a VALUE position: `key: <cursor>` ──────────────────────────────────────────
+    const atValue = /^\s*-?\s*"?([A-Za-z_][\w.-]*)"?\s*:\s*"?([\w.\-/]*)$/.exec(upto);
+    if (atValue) {
+      const [, key, typed] = atValue;
+      const from = ctx.pos - typed.length;
+      const list = (items: string[], detail: string, type = "constant"): CompletionResult => ({
+        from,
+        options: items.map((i) => opt(i, detail, type)),
+        validFor: /^[\w.\-/]*$/,
+      });
+
+      if (key === "type") return list(vocab.primitives, "primitive", "class");
+      if (key === "ref") return list(vocab.atoms, "atom", "variable");
+      if (key === "select" || key === "component") return list(vocab.components, "component", "class");
+      if (COLOR_KEYS.has(key)) return list(vocab.tokens.color, "colour token");
+      if (key === "font") return list(vocab.tokens.font, "type scale");
+      if (key === "lineHeight") return list(vocab.tokens.lineHeight, "line height");
+      if (key === "radius" || key.startsWith("radius")) return list(vocab.tokens.radius, "radius token");
+      if (key === "shadow") return list(vocab.tokens.shadow, "shadow token");
+      if (vocab.dimensionKeys.includes(key)) return list(vocab.tokens.space, "space step");
+      return null;
+    }
+
+    // ── a KEY position: the start of a line ────────────────────────────────────────
+    const atKey = /^\s*-?\s*"?([A-Za-z_][\w.-]*)?$/.exec(upto);
+    if (atKey) {
+      const typed = atKey[1] ?? "";
+      const from = ctx.pos - typed.length;
+      const parent = enclosingKey(lines, row, indentOf(line.text));
+      if (parent === "style" || parent === "hover")
+        return {
+          from,
+          options: vocab.styleKeys.map((k) => opt(k, "style key", "property")),
+          validFor: /^[\w-]*$/,
+        };
+      if (parent === "visibleWhen" || parent === "when")
+        return {
+          from,
+          options: vocab.conditionKeys.map((k) => opt(k, "condition", "property")),
+          validFor: /^[\w-]*$/,
+        };
+    }
+
+    return null;
+  };
+}

package/screens/source/highlight.ts

@@ -0,0 +1,72 @@
+/**
+ * THE OVERLAY: draw a box over the rendered element the cursor is in.
+ *
+ * The preview renders inside a shadow root, so a plain `document.querySelectorAll` finds
+ * nothing: shadow DOM is exactly the boundary that hides it. The search descends through
+ * every open shadow root instead.
+ *
+ * The boxes are drawn in the LIGHT DOM, positioned from each element's viewport rect. That
+ * keeps the preview's own tree untouched, which matters because the thing being inspected
+ * is a live render and inserting nodes into it would change what is being inspected.
+ */
+
+const LAYER_ID = "unoverse-inspect-layer";
+
+/** Every element with this attribute value, descending through open shadow roots. */
+function findAll(root: ParentNode, selector: string, out: Element[] = []): Element[] {
+  out.push(...Array.from(root.querySelectorAll(selector)));
+  for (const el of Array.from(root.querySelectorAll("*"))) {
+    const shadow = (el as Element & { shadowRoot?: ShadowRoot | null }).shadowRoot;
+    if (shadow) findAll(shadow, selector, out);
+  }
+  return out;
+}
+
+function layer(): HTMLElement {
+  let el = document.getElementById(LAYER_ID);
+  if (!el) {
+    el = document.createElement("div");
+    el.id = LAYER_ID;
+    el.style.cssText = "position:fixed;inset:0;pointer-events:none;z-index:60";
+    document.body.appendChild(el);
+  }
+  return el;
+}
+
+/** Remove any boxes currently drawn. */
+export function clearHighlight(): void {
+  document.getElementById(LAYER_ID)?.replaceChildren();
+}
+
+/**
+ * Box every element rendered from `id`.
+ *
+ * Returns how many were found. Zero is a real answer rather than a failure: the node under
+ * the cursor may be in an inactive `Switch` case, hidden by `visibleWhen`, or in a file
+ * that is not part of what is on screen.
+ */
+export function highlightRendered(id: string | null, accent = "#3b82f6"): number {
+  const host = layer();
+  host.replaceChildren();
+  if (!id) return 0;
+
+  const els = findAll(document, `[data-unoverse-id="${CSS.escape(id)}"]`);
+  for (const el of els) {
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 && r.height === 0) continue;
+    const box = document.createElement("div");
+    box.style.cssText = [
+      "position:absolute",
+      `left:${r.left}px`,
+      `top:${r.top}px`,
+      `width:${r.width}px`,
+      `height:${r.height}px`,
+      `outline:2px solid ${accent}`,
+      `background:${accent}1f`,
+      "border-radius:2px",
+      "transition:all .08s ease-out",
+    ].join(";");
+    host.appendChild(box);
+  }
+  return els.length;
+}

package/screens/source/inspect.ts

@@ -0,0 +1,103 @@
+/**
+ * CURSOR TO ELEMENT: which rendered thing is the line under the cursor?
+ *
+ * The renderer stamps each node's path onto the element it draws (`data-unoverse-id`), and
+ * `stampPaths` is what assigns those paths. Both the host (before rendering) and the editor
+ * (to look one up) stamp the same tree the same way, which is why this is one function
+ * rather than two that must agree.
+ *
+ * The editor holds a SOURCE FILE, which is usually a partial: a layout is included into a
+ * face, so a path inside the file is not the path in the composed tree. `locateSubtree`
+ * bridges that by finding where the file's tree sits inside the composed one.
+ */
+
+/** Record each node's path on it as `$id`. Only objects with a `type` render. */
+export function stampPaths(node: unknown, path: string): void {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    node.forEach((child, i) => stampPaths(child, `${path}.${i}`));
+    return;
+  }
+  const n = node as Record<string, unknown>;
+  if (typeof n.type === "string") n.$id = path;
+  for (const [k, v] of Object.entries(n)) {
+    if (k !== "$id" && v && typeof v === "object") stampPaths(v, `${path}.${k}`);
+  }
+}
+
+/**
+ * Drop every `$`-prefixed key, so a file and the composed tree compare on content alone.
+ *
+ * Not just my own `$id`: a source file also carries `$schema` for editor support, and the
+ * server strips it when composing. Comparing `$id` only meant a layout file never matched
+ * the node it produces, and every line in it reported "not rendered".
+ */
+function withoutMeta(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(withoutMeta);
+  if (!value || typeof value !== "object") return value;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    if (!k.startsWith("$")) out[k] = withoutMeta(v);
+  }
+  return out;
+}
+
+/**
+ * The composed path of the first node whose content matches `subtree`, or null.
+ * Definitions are small and the match is exact, so this is cheap and unambiguous.
+ */
+export function locateSubtree(composed: unknown, subtree: unknown): string | null {
+  const target = JSON.stringify(withoutMeta(subtree));
+  let found: string | null = null;
+  const walk = (node: unknown): void => {
+    if (found || !node || typeof node !== "object") return;
+    if (Array.isArray(node)) return node.forEach(walk);
+    const n = node as Record<string, unknown>;
+    if (typeof n.type === "string" && typeof n.$id === "string" && JSON.stringify(withoutMeta(n)) === target) {
+      found = n.$id;
+      return;
+    }
+    Object.values(n).forEach(walk);
+  };
+  walk(composed);
+  return found;
+}
+
+/** The innermost node containing `offset`. */
+export function pathAtOffset(ranges: { path: string; from: number; to: number }[], offset: number): string | null {
+  let best: { path: string; span: number } | null = null;
+  for (const r of ranges) {
+    if (offset < r.from || offset > r.to) continue;
+    const span = r.to - r.from;
+    if (!best || span < best.span) best = { path: r.path, span };
+  }
+  return best?.path ?? null;
+}
+
+/**
+ * Every node's path and source range in a parsed YAML document.
+ *
+ * A NODE IS ONE WHOSE `type` IS A PRIMITIVE. A prop declaration also carries a `type`
+ * (`type: string`), so accepting any string made every prop look like a node: the cursor
+ * anywhere in `props` reported a node that had of course rendered nothing. The primitive
+ * set is the discriminator, and it comes from the same vocabulary the linter enforces.
+ *
+ * Ranges are the parser's, so they are where a node actually starts and ends rather than a
+ * guess from indentation.
+ */
+export function nodeRanges(doc: unknown, primitives: Set<string>): { path: string; from: number; to: number }[] {
+  const out: { path: string; from: number; to: number }[] = [];
+  if (!primitives.size) return out;
+  const walk = (node: any, path: string): void => {
+    if (!node?.items || !Array.isArray(node.items)) return;
+    // A mapping's items are key/value pairs; a sequence's items are nodes.
+    node.items.forEach((item: any, i: number) => {
+      if (item?.key !== undefined && item?.value !== undefined) walk(item.value, `${path}.${String(item.key.value ?? item.key)}`);
+      else walk(item, `${path}.${i}`);
+    });
+    const isNode = node.items.some((it: any) => it?.key?.value === "type" && primitives.has(it?.value?.value));
+    if (isNode && Array.isArray(node.range)) out.push({ path, from: node.range[0], to: node.range[2] ?? node.range[1] });
+  };
+  walk((doc as { contents?: unknown }).contents, "root");
+  return out;
+}

package/screens/source/picker.ts

@@ -0,0 +1,89 @@
+/**
+ * PICK AN ELEMENT, LAND ON THE LINE. The inspector, the other way round.
+ *
+ * Hover the preview, the element under the pointer is boxed, click and the editor opens the
+ * file that drew it with the cursor on the node. The link is the `data-unoverse-id` the
+ * renderer stamps, so this needs no new machinery, only the reverse lookup.
+ *
+ * Two things the DOM makes awkward, both handled here:
+ *
+ *   SHADOW ROOTS. The preview renders inside one, so `elementFromPoint` returns the HOST
+ *   rather than what is under the pointer. Descending through each root gets the real one.
+ *
+ *   NOT EVERY ELEMENT IS A NODE. A primitive renders one element, but that element has
+ *   children of its own, so the pointer often lands on something unstamped. Walking up to
+ *   the nearest ancestor carrying an id gives the node a developer means.
+ */
+
+/** The deepest element under the point, descending through open shadow roots. */
+export function deepElementFromPoint(x: number, y: number): Element | null {
+  let el = document.elementFromPoint(x, y);
+  for (;;) {
+    const shadow = (el as (Element & { shadowRoot?: ShadowRoot | null }) | null)?.shadowRoot;
+    const inner = shadow?.elementFromPoint(x, y);
+    if (!inner || inner === el) return el;
+    el = inner;
+  }
+}
+
+/** The nearest stamped ancestor, crossing shadow boundaries the way `closest` will not. */
+export function stampedAncestor(el: Element | null): { el: Element; id: string } | null {
+  let cur: Element | null = el;
+  while (cur) {
+    const id = cur.getAttribute?.("data-unoverse-id");
+    if (id) return { el: cur, id };
+    cur = cur.parentElement ?? ((cur.getRootNode() as ShadowRoot).host ?? null);
+  }
+  return null;
+}
+
+export interface SourceLocation {
+  /** Absolute path of the file that draws this node. */
+  path: string;
+  /** Character offset of the node in that file. */
+  from: number;
+}
+
+/**
+ * Where each composed node is authored, across a component's files.
+ *
+ * Built by parsing every YAML file, finding where its tree sits in the composed one, and
+ * recording the composed id of each node against its offset in that file. It is built once
+ * when the picker is armed rather than on every hover, because a component has a dozen
+ * files and a hover has a frame.
+ */
+export function buildSourceMap(
+  files: { path: string; rel: string; text: string }[],
+  composedRoot: unknown,
+  primitives: Set<string>,
+  parse: (text: string) => unknown,
+  nodeRanges: (doc: unknown, primitives: Set<string>) => { path: string; from: number; to: number }[],
+  locateSubtree: (composed: unknown, subtree: unknown) => string | null,
+  toJS: (doc: unknown) => unknown,
+): Map<string, SourceLocation> {
+  const map = new Map<string, SourceLocation>();
+  for (const file of files) {
+    let doc: unknown;
+    try {
+      doc = parse(file.text);
+    } catch {
+      continue; // a file that does not parse simply contributes nothing
+    }
+    const js = toJS(doc) as Record<string, unknown> | null;
+    if (!js || typeof js !== "object") continue;
+
+    // An envelope's tree IS the composed root; a partial has to be located inside it.
+    const isEnvelope = !js.type && !!js.root;
+    const prefix = isEnvelope ? "root" : locateSubtree(composedRoot, js);
+    if (!prefix) continue;
+    const strip = isEnvelope ? "root.root".length : "root".length;
+
+    for (const r of nodeRanges(doc, primitives)) {
+      const id = `${prefix}${r.path.slice(strip)}`;
+      // FIRST WRITER WINS. A node's own file is reached before any file that includes it,
+      // so the deepest authored source keeps the entry.
+      if (!map.has(id)) map.set(id, { path: file.path, from: r.from });
+    }
+  }
+  return map;
+}

package/src/host.ts

@@ -13,6 +13,7 @@
  */
 import { useCallback, useEffect, useState } from "react";
 import type { ResolvedTheme, UnoverseDefinition, UnoverseClient } from "@unoverse/sdk";
+import { stampPaths } from "../screens/source/inspect";
 
 /** Everything is same-origin: the Vite dev server serves both the app and the routes. */
 export const UNOVERSE_BASE = "";
@@ -20,6 +21,17 @@ export const UNOVERSE_BASE = "";
 /** No login offline. Kept so the shared screens can ask without branching on host. */
 export const hasAuth = false;
 
+/**
+ * SOURCE ACCESS: this host serves the files behind a definition, so the screens may show
+ * the source view. Local Studio reads the developer's own folder, so it can.
+ *
+ * The capability lives on the host for the reason `hasAuth` does: a shared screen must
+ * never branch on which app it is running in. Canvas leaves it false, so hosted surfaces
+ * render and never edit, by construction rather than by discipline
+ * (docs/architecture/LOCAL_STUDIO.md §The capability gate).
+ */
+export const hasSourceAccess = true;
+
 /** Plain fetch. The bearer the Canvas host attaches has no meaning against a folder. */
 export async function authedFetch(input: string, init?: RequestInit): Promise<Response> {
   return fetch(input, init);
@@ -82,10 +94,23 @@ class LocalUnoverseClient {
     );
   }
 
+  /**
+   * Read a definition, and STAMP EVERY NODE WITH ITS PATH.
+   *
+   * The renderer copies a node's `$id` onto the element it draws, which is what lets the
+   * editor highlight the thing under the cursor. The id is the node's path in this
+   * COMPOSED tree (`root.children.0.children.1`), assigned here because the host is the
+   * last place that sees the tree before the renderer does.
+   *
+   * Local Studio only. A universe serves definitions to real users, who have no editor to
+   * link to and no business carrying authoring metadata.
+   */
   async readDefinition(uri: string): Promise<UnoverseDefinition> {
     const r = await fetch(`/local/definition?uri=${encodeURIComponent(uri)}`);
     if (!r.ok) throw new Error(`${uri}: ${(await r.json().catch(() => ({}))).error ?? r.status}`);
-    return (await r.json()) as UnoverseDefinition;
+    const def = (await r.json()) as UnoverseDefinition;
+    stampPaths((def as { root?: unknown }).root, "root");
+    return def;
   }
 
   async readTheme(name = "light"): Promise<ResolvedTheme> {

package/vendor/sdk/appEngine.tsx

@@ -208,6 +208,7 @@ export function AppEngine(cfg: AppConfig) {
         if (conn.resolveElicitation(state)) return;
         conn.sendAction(t, {
           componentNodeId: meta?.nodeId,
+          componentType: meta?.type,
           // The component's OWN chatId is the TURN id — the waiting node execution is
           // keyed `<turn>:<nodeId>`, not the conversation-level chatId.
           componentChatId: meta?.chatId,