@unoverse-platform/studio 0.1.28 → 0.1.29

package/local/plugin.ts

@@ -368,7 +368,12 @@ export function localStudioHost(): Plugin {
               // Apps are addressed both ways (unoverse://apps/<org>/<id> and
               // unoverse://templates/<org>/<id>); both load the template kind.
               const kind = /\/(apps|templates)\//.test(uri) ? "template" : /\/atoms\//.test(uri) ? "atom" : "component";
-              const ref = uri.replace(/^unoverse:\/\/(components|atoms|apps|templates)\//, "");
+              // A trailing `@form` is a request for a VARIANT of the definition, not part of
+              // its name. This door did not know that convention and looked up the whole
+              // string, so every component read as `<name>@refs` answered "definition not
+              // found". Strip any variant: this route serves the one form it has, which is
+              // also the only form the server serves.
+              const ref = uri.replace(/^unoverse:\/\/(components|atoms|apps|templates)\//, "").replace(/@[a-z]+$/, "");
               const d = c.loadDefinition(ref, kind);
               return d ? json(res, d) : json(res, { error: `definition not found: ${uri}` }, 404);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unoverse-platform/studio",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "type": "module",
   "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
   "scripts": {

package/vendor/sdk/appEngine.tsx

@@ -21,6 +21,7 @@ import {
   setAnalyticsContext,
   setAnalyticsDebug,
   type UseVoiceServiceConfig,
+  type UnoverseDefinition,
 } from "./lib";
 
 export interface AppConfig {
@@ -56,7 +57,14 @@ export function AppEngine(cfg: AppConfig) {
   // STATE-OWNED WIDTH (rx data): the layout root's `appWidth` = the core surface's
   // constant width; an occupied panel slot's `appWidth` adds to it (computeAppWidth).
   // No declared width → the host keeps its own default. There is no other path.
-  const [def, setDef] = useState<{ root?: unknown; org?: string; layouts?: Record<string, unknown>; defaultLayout?: string } | null>(null);
+  // THE WHOLE DEFINITION, not a chosen four fields. This used to keep `{root, org, layouts,
+  // defaultLayout}` and drop everything else, which is a whitelist that silently loses each
+  // field the contract gains. It was dropping `stateOrder`, `publicStates`, `initialView`
+  // and `stateTree`, quietly running the v2 ladder in legacy mode, and it dropped `defs`
+  // too: with shared pieces unreachable, the core panel's `appWidth` went uncounted and the
+  // app's width collapsed to the open surface's remainder term, which is negative, so the
+  // app rendered 0 pixels wide and blank.
+  const [def, setDef] = useState<UnoverseDefinition | null>(null);
   const lastWidthRef = useRef<string | undefined>(undefined);
   // Named app sizes resolve via the served theme (theme.appSize), like every token.
   const theme = useUnoverseTheme(client, def ? (def.org ? `${def.org}/light` : "light") : null);
@@ -80,10 +88,9 @@ export function AppEngine(cfg: AppConfig) {
     // definition too — same resource the renderer loads.
     client
       .connect()
-      .then(() => client.readDefinition(`unoverse://templates/${templateId}@refs`))
+      .then(() => client.readDefinition(`unoverse://templates/${templateId}`))
       .then((d) => {
-        const t = d as { root?: unknown; org?: string; layouts?: Record<string, unknown>; defaultLayout?: string } | null;
-        if (alive) setDef(t ? { root: t.root, org: t.org, layouts: t.layouts, defaultLayout: t.defaultLayout } : null);
+        if (alive) setDef(d ?? null);
       })
       .catch((e) => console.error("[app] template read failed:", e));
     return () => {
@@ -114,7 +121,7 @@ export function AppEngine(cfg: AppConfig) {
     const report = () => {
       // NAME-SYNC: width is computed off the ACTIVE layout (multi-layout templates
       // swap whole arrangements); single-layout defs resolve to their root.
-      const w = computeAppWidth(resolveActiveLayout(def as never, store), store, theme?.appSize, def as never);
+      const w = computeAppWidth(resolveActiveLayout(def, store), store, theme?.appSize, def);
       if (w && w !== lastWidthRef.current) {
         lastWidthRef.current = w;
         window.parent?.postMessage({ type: "unoverse:size", width: w }, "*");
@@ -183,7 +190,7 @@ export function AppEngine(cfg: AppConfig) {
     <StreamedUnoverseTemplate
       client={client}
       store={store}
-      uri={`unoverse://templates/${templateId}@refs`}
+      uri={`unoverse://templates/${templateId}`}
       voice={voiceConfig}
       onAction={(action, data, meta) => {
         const t = typeof action === "string" ? action : (action as any)?.type;

package/vendor/sdk/lib/UnoverseComponent.tsx

@@ -83,11 +83,11 @@ export function UnoverseComponent({ client, uri, data, store, chatId, nodeId, ex
   // LIVE SOURCE. The hook runs either way (hooks cannot be conditional) and no-ops without a
   // store, so one component serves both paths without a wrapper deciding for it.
   const live = useUnoverseInstance(store, chatId, nodeId);
-  // `@refs` asks for the REFERENCED form: shared pieces named once and shipped once,
-  // rather than a copy pasted at every use (746 KB became 221 KB across five real
-  // definitions). This client resolves them, so it asks; a client that could not would
-  // render a hole, which is why the bare URI still serves the inlined form.
-  const resolvedUri = store ? (live.type ? `unoverse://components/${live.type}@refs` : null) : (uri ?? null);
+  // The BARE URI, deliberately. This asked for the referenced form (`@refs`) while that
+  // form existed; it is withdrawn (server resources.ts refForm), so asking for it now only
+  // spreads a suffix that every door has to know how to strip. Studio's own local
+  // definition route did not, and answered "definition not found" for every component.
+  const resolvedUri = store ? (live.type ? `unoverse://components/${live.type}` : null) : (uri ?? null);
   const sourceData = store ? (extraData ? { ...(live.data ?? {}), ...extraData } : live.data) : data;
   // No theme passed → fetch it from the server (the SDK owns zero token values). The
   // theme REF comes from the definition itself: a template's `org` names its client's

package/vendor/sdk/lib/core/store.ts

@@ -196,6 +196,31 @@ export class ComponentStore {
     if (changed) this.bump();
   }
 
+  /**
+   * A HIGHER STATE CLEARS THE STATES BELOW IT (STATE_MODEL §5, THE SEVEN RULES rule 4) —
+   * when a DELIVERY put it there. Every component sitting in a lower-ranked state releases
+   * its claim, so rule 6's re-walk finds nothing below and lands on the BASE. The caller
+   * decides delivery-vs-guest (`resolveActiveView().byGuest`): the guest's own navigation
+   * clears nothing, or closing a page would have nothing to return to.
+   *
+   * Retracts to `inline`, not through `retractSlice`: that helper targets the slice's
+   * declared initial, and a card whose initial IS the lower state would re-claim it on
+   * the next walk and never settle.
+   */
+  cancelBelow(active: string, order: string[]): void {
+    const below = new Set(order.slice(order.indexOf(active) + 1));
+    if (order.indexOf(active) < 0 || !below.size) return;
+    let changed = false;
+    for (const [key, slice] of this.data) {
+      if (slice.lifetime === "conversation") continue;
+      if (!below.has((slice.view ?? slice.defaultState) as string)) continue;
+      this.data.set(key, { ...slice, ...("defaultState" in slice ? { defaultState: "inline" } : { view: "inline" }) });
+      this.touches.set(key, ++this.touchSeq);
+      changed = true;
+    }
+    if (changed) this.bump();
+  }
+
   closeSurfaces(): void {
     let changed = false;
     for (const [key, slice] of this.data) {

package/vendor/sdk/lib/core/types.ts

@@ -123,9 +123,12 @@ export interface UnoverseDefinition {
   description?: string;
   /**
    * REFERENCE, DON'T COPY: the shared pieces this definition NAMES, by ref name, each
-   * shipped once instead of pasted at every use. Present only when the definition was
-   * read as `<uri>@refs`; the bare URI still serves fully inlined trees, so a renderer
-   * without `Ref` support is never handed one it cannot draw.
+   * shipped once instead of pasted at every use.
+   *
+   * NEVER PRESENT TODAY. The server withdrew the referenced form (server resources.ts
+   * `refForm`) after it left an app rendering zero pixels wide, and no client asks for it.
+   * The field and `resolveRef` stay because the resolution is correct and proven; what is
+   * missing is end-to-end proof and an answer for every client version in the estate.
    */
   defs?: Record<string, UnoverseNode>;
   /** EXTERNAL contract — the rare workflow-fed inputs (`input: true`). A contained

package/vendor/sdk/lib/template.tsx

@@ -141,12 +141,6 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
       }
   }, [def, store, structureVersion]);
 
-  // THE SEVEN RULES (2026-08-09) need no effect here: a higher state MASKS the ones
-  // below (rule 4 — the ladder alone decides what shows; lower states refresh
-  // silently underneath via the store's arrival supersession), and releasing the top
-  // state is just the ladder looking again (rule 6). The earlier cancellation WRITE
-  // (cancelBelow) was superseded by this pure-masking ruling and deleted.
-
   // STATE OWNS LAYOUT (STATE_MODEL v2): the tree this template presents — the active
   // state's layout (multi-layout templates), else the classic root. The resolved node
   // is a stable per-def object, so downstream memos key off it.
@@ -162,6 +156,24 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
     return views;
   }, [activeRoot, def]);
 
+  // RULE 4: the winner clears the states below it — WHEN A DELIVERY PUT IT THERE.
+  // An arrival taking a higher rung means the screen has moved on, so stale claims below
+  // it let go and rule 6's re-walk lands on the base. The guest's own navigation is not
+  // that: tapping a rail card to open its page must leave the rail's claims intact, or
+  // closing the page has nothing to return to. Priority still decides what SHOWS in both
+  // cases; this only decides what gets thrown away. Derived above the loading guards so
+  // this stays a hook, and off the SAME derivation the render path uses.
+  const ladder = def ? resolveActiveView(def, store, surfacedViews) : { view: "", byGuest: false };
+  useEffect(() => {
+    if (ladder.view && !ladder.byGuest) store.cancelBelow(ladder.view, orderedClaims(def));
+    // `structureVersion`: EVERY arrival re-runs this, not only the ones that change the
+    // winner. A card landing while a higher state is ALREADY active would otherwise keep
+    // its claim forever — the walk never re-ran — and closing the higher state dropped
+    // straight onto it (observed: a rail still there after a focus surface closed, because
+    // the card's render landed two seconds after the finder took focus). `cancelBelow`
+    // only bumps when it changed something, so this settles in one extra pass.
+  }, [ladder.view, ladder.byGuest, def, store, structureVersion]);
+
   // Loading/error hints carry NO styling — the SDK owns zero styles.
   if (error) return <div>Unoverse error: {error}</div>;
   if (!def || !theme) return <div>Loading {uri}…</div>;