@unoverse-platform/studio 0.1.30 → 0.1.32

package/bin/studio.mjs

@@ -17,7 +17,7 @@
  * universe, which is a different job. See docs/architecture/LOCAL_STUDIO.md.
  */
 import { createServer } from "vite";
-import { dirname, resolve, join } from "path";
+import { dirname, resolve, join, basename } from "path";
 import { fileURLToPath } from "url";
 import { existsSync, readdirSync } from "fs";
 import { createInterface } from "readline/promises";
@@ -33,8 +33,9 @@ const appRoot = resolve(here, "..");
  * which is a tool telling you to do the thing it could do. The first thirty seconds of a
  * new install should end with something on screen, not with a mkdir.
  *
- * It asks rather than assumes: creating folders in whatever directory somebody happens to
- * be in is not a thing to do quietly. Answer no and the original message stands.
+ * It creates rather than asks. Standing in an empty folder you made and typing this IS the
+ * instruction; the folder says where and its name says what. The only question left is the
+ * one it cannot answer for you: a folder whose name no project can carry.
  */
 /** The same walk `catalog.ts` does: the nearest folder above us holding rx/. */
 function findProjectRootFromCwd() {
@@ -92,45 +93,40 @@ async function scaffoldIfEmpty() {
     return;
   }
 
-  console.log(`\n  No project here yet.\n\n  ${cwd}\n`);
-
   /**
-   * THE HOLDER IS CALLED `studio`. THE NAME YOU TYPE IS A PROJECT INSIDE IT.
-   *
-   * Studio used to scaffold into the cwd, which made whatever directory you were standing
-   * in your repository. Fixing that by naming the folder after the project overcorrected:
-   * it produced `sab/rx/sab`, and it said the wrong thing about what the folder IS.
+   * THE WORKSPACE IS THE FOLDER YOU ARE STANDING IN, and the project takes its name.
    *
-   * This folder is not a project. It is the workspace a developer authors in, holding
-   * `prompts/`, `nodes/`, one `.claude/` skill and an `rx/` of MANY projects — every one
-   * of which is an org that publishes under its own name. Naming it after the first
-   * project claims the second one belongs to the first, and the fifth project makes that
-   * plainly false while the folder still carries the first one's name.
+   * Two earlier shapes invented a folder instead of accepting the one the developer had
+   * chosen: `rx/<name>/` into ANY cwd (so a scratch folder became a repository), then the
+   * typed name owning a folder, then a fixed `studio/` holder — which buried the project
+   * one level inside the folder made for it, and asked for a name it could already see.
+   * Standing in `~/code/bpp` and typing `unoverse studio` says both things: here, and bpp.
    *
-   * So the holder is always `studio/`, and the name you typed is where it belongs: the
-   * project, at `rx/<name>/`.
+   * A workspace does hold MANY projects (`rx/` is one folder per publishing org), and the
+   * folder carrying the first one's name is why the holder was introduced. That is a cost
+   * paid at project five, by a developer who can rename the folder; it does not buy the
+   * confusion of an extra level in the first thirty seconds.
    */
-  const home = join(cwd, "studio");
-  if (existsSync(home) && readdirSync(home).some((f) => !f.startsWith("."))) {
-    // Not a re-prompt: a different project name would not make this folder free, and the
-    // loop below would ask forever. (A `studio/` that IS a project was already found and
-    // entered above, so getting here means it is something else.)
-    console.log(`  ./studio already has something in it, and it is not a Studio workspace.\n`);
-    process.exit(1);
-  }
-
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-
-  // Ask until the name is usable. It becomes a folder AND an item's `org` column, so a
-  // rejection here is cheaper than a rename after something has been published.
-  let name;
-  for (;;) {
-    name = (await rl.question("  Name your project [my-project]: ")).trim() || "my-project";
-    const bad = checkProjectName(name);
-    if (!bad) break;
-    console.log(`  ${bad}\n`);
+  const home = cwd;
+  // The folder's own name, when it can be a project name. It becomes an item's `org`
+  // column, so `checkProjectName` is the same gate the UI's New project uses.
+  const derived = basename(cwd);
+  let name = checkProjectName(derived) ? null : derived;
+
+  if (!name) {
+    // NOTHING TO DERIVE — the folder is called something no project can be called
+    // (capitals, dots, a leading digit). This is the only case that still asks.
+    console.log(`\n  No project here yet.\n\n  ${cwd}\n`);
+    console.log(`  "${derived}" cannot be a project name (lowercase letters, numbers and dashes).\n`);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    for (;;) {
+      name = (await rl.question("  Name your project [my-project]: ")).trim() || "my-project";
+      const bad = checkProjectName(name);
+      if (!bad) break;
+      console.log(`  ${bad}\n`);
+    }
+    rl.close();
   }
-  rl.close();
 
   // The same call the UI's New project makes, so the first project and the fifth are
   // identical (local/scaffold.mjs). rx/<name>/ stays nested: every subfolder of rx/ IS a
@@ -138,9 +134,7 @@ async function scaffoldIfEmpty() {
   // publishes, so a flat rx/ could hold exactly one project and would read `components`
   // and `templates` as orgs.
   createFirstProject(home, name);
-  // Studio reads from the cwd, and the project is no longer the folder we launched in.
-  process.chdir(home);
-  console.log(`\n  Created studio/ with rx/${name}/, prompts/ and nodes/\n`);
+  console.log(`\n  Created rx/${name}/, prompts/ and nodes/ in ${cwd}\n`);
 }
 
 await scaffoldIfEmpty();

package/package.json

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

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

@@ -39,6 +39,16 @@ const clone = <T,>(v: T): T => JSON.parse(JSON.stringify(v)) as T;
 /** `props` remaps the atom's OWN field names to the host's fields, everywhere a field name
  *  can appear: binds, both spellings of `visibleWhen`, and `style.when` predicates. */
 function remapFields(node: AnyNode, propMap: Record<string, string>): void {
+  // A NESTED `Ref` is remapped through its OWN `props`, whose values name fields in THIS
+  // tree's scope. An atom that composes another atom (toggle-row, form-toggle → toggle-switch)
+  // otherwise passes the inner one a name the host has renamed away, and the inner control
+  // reads an absent key: it draws, it just never reflects anything.
+  if (node.type === "Ref" && node.props && typeof node.props === "object") {
+    for (const k of Object.keys(node.props as AnyNode)) {
+      const v = (node.props as AnyNode)[k];
+      if (typeof v === "string" && propMap[v]) (node.props as AnyNode)[k] = propMap[v];
+    }
+  }
   if (node.bind) for (const k of Object.keys(node.bind)) if (propMap[node.bind[k]]) node.bind[k] = propMap[node.bind[k]];
   if (typeof node.visibleWhen === "string" && propMap[node.visibleWhen]) node.visibleWhen = propMap[node.visibleWhen];
   // The OBJECT form remaps too. A guard is a guard whichever way it is written; carrying

package/vendor/skills/unoverse-create/references/component.md

@@ -135,7 +135,7 @@ The rules, in the order they bite:
    of bound fields). Same shape, different values = ONE state, data-driven: seven wizard
    questions sharing one shape are one `question` state whose data changes, never seven
    files (LAYERS §4, §7).
-5. **Atoms** (`rx/atoms/`, via `Ref`) are for shapes shared across components, authoring-time
+5. **Atoms** (`rx/marketplace/atoms/`, via `Ref`) are for shapes shared across components, authoring-time
    only (the server expands them before serving; no Studio view). `Ref props` remaps FIELDS;
    **`Ref with` passes LITERALS**: `{ "type": "Ref", "ref": "button", "with": { "label":
    "Learn more", "icon": "arrowRight" }, "action": { … } }`. A bind whose field is a `with`
@@ -157,38 +157,83 @@ The rules, in the order they bite:
    for surgical refinement). **The schema IS the instruction channel.**
    Write briefs, never side-channel prompts/skills for filling a component. Shape is
    closed + linted. Pairs with the single-state permanent pattern (rule 2) for
-   continuously-enriched pages; exemplar: `rx/components/perfectday`.
+   continuously-enriched pages; exemplar: `rx/yasisland/components/perfect-day`.
 7. **Tokens only** (LAW 1) + closed style keys + real space-scale steps
    (`docs/design/06`): an invented step is silently broken CSS.
-8. **Lifecycle handlers: a component's own server-side code** (deep law:
-   [UNOVERSE_AUTHORING](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_AUTHORING.md) §3c). When a component needs live data from an
-   API or a computation (not from an AI = brief, not from the workflow = `input` props), it
-   may bring a small server-side script that runs when the component renders. It's for DATA,
-   not styling or logic-in-the-def.
-   - **Opt in via the manifest** (authorizes execution; auditable): `"lifecycle":
-     ["onStart"]` in the manifest. A handler file with no opt-in is INERT.
-   - **The code is a sibling file named for the lifecycle**: `onStart` → `onstart.js`,
-     beside the root file. Its **default export** is the handler.
-   - **`onStart`** is the only lifecycle today; it runs SERVER-SIDE when the instance is
-     created (the MCP render path), and whatever it returns is **merged into the instance
-     by prop name** (unknown keys inert, same contract as workflow-fed props). Return only
-     the fields you're filling; **never overwrite a curated prop** you didn't intend to.
-   - **`ctx` is a bounded sandbox**: `ctx.props` (the instance's current data),
-     `ctx.instanceId`, `ctx.env(name)` (server config). The **API key comes from
-     `ctx.env`, NEVER hardcoded**: `rx/` is a shared design folder; a secret in it leaks.
-   - Self-contained (the external call lives in the handler); errors never break the render.
-   Exemplar: `rx/yasisland/components/restaurantcard/onstart.js` (Google Maps details).
-
-   ```js
-   // onstart.js: manifest opts in with "lifecycle": ["onStart"]
-   export default async function onStart(ctx) {
-     const key = ctx.env("SEARCHAPI_KEY");                 // secret from server config
-     const res = await fetch(`https://…&q=${encodeURIComponent(ctx.props.title)}&api_key=${key}`);
-     const place = (await res.json()).local_results?.[0] ?? {};
-     return { rating: place.rating, address: place.address };   // merged by prop name
-   }
+8. **Lifecycle hooks: the component fetches its own data** (full doc:
+   `docs/design/lifecycle-hooks.md`; deep law:
+   [UNOVERSE_AUTHORING](https://github.com/unoverse-platform/docs/blob/main/unoverse/UNOVERSE_AUTHORING.md) §3c). When a component needs data the
+   workflow did not send (not from an AI = brief, not from the workflow = `input` props),
+   it declares CALLS that the platform runs at a platform-owned fire point. **No code**:
+   a hook is data like everything else in `rx/`. It's for DATA, not styling or logic.
+   - **Two phases**: `onStart` (the instance is created: data every copy needs) and
+     `onEnterView` (the instance entered a named STATE: data only that state needs). A
+     detail view's content is `onEnterView`, NEVER `onStart` — hydrating at creation
+     fetches a full document for every card in a grid.
+   - **Opt in via the manifest** (authorizes execution; auditable). Nothing undeclared
+     runs; an un-opted handler file is a lint error, not an inert file.
+   - **The scope key is spelled `layouts:` but its entries are STATE names.**
+     `onEnterView` only. Omit it and every state fires.
+   - **Name the handler for what it DOES, never for the phase** (`fetchPlaceDetails`, not
+     `onEnterView`): the phase already said the moment.
+   - **Nothing to wire up.** A component changing its own view writes `view`, and that
+     write IS the event the hook reacts to. No signal to author, no action to chain.
+   - **Prefer a platform-ready handler.** `getDetail` (zero code) reads the instance's
+     `universal_id` and merges the stored record's fields in by name, so authored copy
+     never travels through a model. Use it for "fill this card with its own record".
+
+   ```yaml
+   # manifest.yaml — the shipped rx/sab/components/product-card
+   lifecycle:
+     - phase: onEnterView
+       layouts: [ detail ]      # STATE names; the grid state never wakes it
+       handler: getDetail       # platform-ready, so this component ships no code
+   ```
+
+   - **Beyond the built-ins, DECLARE the calls** in `<handler>.yaml` beside the manifest
+     (**filename = the handler, lowercased**: `fetchPlaceDetails` → `fetchplacedetails.yaml`;
+     macOS ignores the case difference and Linux does not). `calls:` is the same list an
+     `api/run.yaml` holds, run by the same runtime (host allowlist, credentials, retries,
+     timeouts, transports); `returns:` projects the results into partial props, merged by
+     name. Calls run in order and read each other through `calls.<name>`.
+   - **`allowedHosts` in the manifest is NOT optional**: a hook that makes requests
+     without it is a lint ERROR (deny by default). Credentials are named by type in the
+     manifest and resolved server-side from encrypted storage; **a key never sits in
+     `rx/`** (a shared design folder) and never reaches the client.
+   - A phase fires once per instance; enrichment streams in (no blocked render); errors
+     fail quietly, leaving whatever the card already had.
+
+   ```yaml
+   # manifest.yaml
+   lifecycle:
+     - phase: onEnterView
+       layouts: [ focus ]
+       handler: fetchPlaceDetails
+   allowedHosts:                 # deny by default — lint error if calls exist without it
+     - www.searchapi.io
+   credentials:
+     - searchapiCredential       # resolved server-side, never in this folder
    ```
 
+   ```yaml
+   # fetchplacedetails.yaml — the handler, lowercased
+   calls:
+     - name: place
+       method: GET
+       url: https://www.searchapi.io/api/v1/search
+       query: { engine: google_maps, q: "{{ props.title }}" }
+       credential: { scheme: apiKeyQuery, param: api_key, value: "{{ credentials.searchapiCredential.apiKey }}" }
+       transport: json
+   returns: >-
+     return ((p) => p ? { rating: p.rating, address: p.address } : {})((calls.place.local_results || [])[0])
+   ```
+
+   ⚠ A raw `<phase>.js` file beside the manifest (e.g. `onstart.js` with `ctx.env`) is the
+   LEGACY form. It still runs for handlers that predate declared calls, but it is **never
+   the one to copy**: a script fetches any host with a key from the environment, and the
+   calls runtime settles both questions.
+   Exemplar: `rx/yasisland/components/restaurant-card/` (maps lookup, declared calls).
+
 ## Discovery meta: write it to RANK (docs/nodes/node-discoverability.md)
 
 A component with a manifest is an **MCP app**: spatial embeds `` `title. whenToUse||description