@mosetta/react 0.0.0-stage → 0.0.9

package/src/react.ts

@@ -0,0 +1,34 @@
+// @mosetta/react — the whole react binding in ONE entry. The former /context, /hooks, /tree
+// and /di subpaths were one organism pretending to be four: everything depends on the same two
+// context instances, a version mismatch kills all of them at once, and every application uses
+// them together. One entry → ONE dependency artifact → the singleton discipline holds by
+// construction. The subpaths that remain (`/start`, `/ssr`, `/server-action`) stay out for
+// closure reasons — react-dom and the action client must not ride into every block — and they
+// link THIS artifact externally.
+export * from './utils/definers';
+export * from './hooks/di';
+export * from './utils/ProvidedContext';
+export * from './hooks/NodeContext';
+export * from './utils/tileReference';
+export * from './utils/previewSlots';
+export * from './hooks/clientState';
+export * from './hooks/usePage';
+export * from './hooks/useRoute';
+export * from './hooks/usePreviewType';
+export * from './hooks/useSettingsDraft';
+export * from './hooks/useEditorContracts';
+export * from './hooks/useMediaUpload';
+export * from './hooks/useTile';
+export * from './hooks/useAddToHead';
+export * from './hooks/useShippedSettings';
+export * from './hooks/useStyler';
+export * from './hooks/useTheme';
+export * from './hooks/useHref';
+export * from './hooks/useRouter';
+export * from './hooks/useResolvedSettings';
+export * from './hooks/useLocalStorageKey';
+export { BlueprintRoot, BlueprintNodeRenderer, NODE_ID_ATTRIBUTE } from './components/BlueprintNodeRenderer';
+export { DefaultRootComponent } from './components/DefaultRootComponent';
+export { Link } from './components/Link';
+export type { ILinkProps } from './components/Link';
+export { ComponentErrorHandler } from './components/ComponentErrorHandler';

package/src/serverAction.ts

@@ -0,0 +1,163 @@
+// useServerAction v2. ONE hook, the `start` axis:
+//   START_FROM_CLIENT (default) — query: auto-starts, cached by <full-id>/<action>#<stable-input>
+//   START_MANUAL               — mutation: no cache, input arrives at data.start(input)
+//   START_FROM_SERVER          — the SSR axis; in the browser behaves as a query (a hydration
+//                                seed from the head cache script covers the precompute)
+//
+// SERVER EXECUTION: when the render carries the ssr channel (→ SsrActionRecorder
+// in DI), START_FROM_SERVER queries run for real through the shared manager — the hook throws
+// the waiter UNCONDITIONALLY (the server render must wait; Suspense-throw is the legacy protocol
+// both runtimes support) and drives the head channel's counter by its rules: begin on the render
+// that ensured the query, complete on the RETRY render that consumed the settled data.
+// The start axis decides WHO pays for the data: START_FROM_CLIENT ships a Loading stub from the
+// server (the client mirrors it and starts the fetch after hydration — parity by stub), manual
+// ships Idle. Channel-less server renders keep the v1 per-hook stubs for everything.
+//
+// DUAL-RUNTIME CONTRACT: this file must run under React (browser) AND preact/compat (the future SSR
+// renderer in the worker — the default React server renderer would tank the isolate's RPS). Only
+// cross-safe primitives: useSyncExternalStore + basic hooks. NO `use()` (absent in preact), no
+// conditional hooks (branches are value-level), no module-level shared state. Opt-in suspense throws
+// the waiter promise — the legacy protocol both runtimes (and preact's renderToStringAsync) support.
+import { useCallback, useState, useSyncExternalStore } from 'react';
+import { useComponent } from '@mosetta/react';
+import { useDi } from '@mosetta/react';
+import {
+  EServerActionStart,
+  EXECUTION_ENV_TOKEN,
+  fullServerTileId,
+  ServerActionToken,
+} from '@mosetta/server-action/core';
+import { DI_CONTAINER_TOKEN } from '@mosetta/di';
+import {
+  ensureServerActionClient,
+  IdleServerData,
+  IServerDataHandle,
+  LoadingServerData,
+  SERVER_DATA_MANAGER,
+  ServerData,
+  SSR_ACTION_RECORDER_TOKEN,
+  stableStringify,
+} from '@mosetta/server-action/client';
+
+export interface IUseServerActionOptions<TIn extends {}, TOut> {
+  readonly token: ServerActionToken<TIn, TOut>;
+  /** query input; MANUAL mode ignores it (the input arrives at data.start(input)) */
+  readonly input?: TIn;
+  /** fixed at mount (changing it later is a programming error, like changing a hook's order) */
+  readonly start?: EServerActionStart;
+  /** opt-in suspense: throw the waiter while Loading (browser only; ignored on the server) */
+  readonly suspense?: boolean;
+  /** merged with token.tags / token.invalidates */
+  readonly tags?: readonly string[];
+  readonly invalidates?: readonly string[];
+}
+
+const RESOLVED = Promise.resolve();
+
+function mergeTags(a?: readonly string[], b?: readonly string[]): readonly string[] {
+  if (!a?.length) return b ?? [];
+  if (!b?.length) return a;
+  return [...new Set([...a, ...b])];
+}
+
+// v1 server behavior (SSR precompute deferred): fresh PER-HOOK stubs — never module-level singletons
+// (a shared subscriber set across concurrent isolate renders was a legacy leak).
+function createServerHandle<TIn, TOut>(isManual: boolean): IServerDataHandle<TOut, TIn> {
+  const snapshot: ServerData<TOut, TIn> = isManual
+    ? new IdleServerData<TOut, TIn>(() => {
+      throw new Error('cannot start a manual server action during server render');
+    })
+    : new LoadingServerData<TOut, TIn>(RESOLVED);
+  return { subscribe: () => () => {}, snapshot: () => snapshot };
+}
+
+export function useServerAction<TIn extends {}, TOut>(
+  options: IUseServerActionOptions<TIn, TOut>,
+): ServerData<TOut, TIn> {
+  const { token } = options;
+  // "carry your own" wiring: the hook lazily wires its own client slice into the top
+  // scope of the inherited per-request container — no root registration, no wrapper component;
+  // the slice code enters a page's closure ONLY through modules that actually call this hook.
+  const di = useDi(DI_CONTAINER_TOKEN);
+  ensureServerActionClient(di);
+  const manager = useDi(SERVER_DATA_MANAGER);
+  const { reference } = useComponent();
+
+  const env = useDi(EXECUTION_ENV_TOKEN);
+  const recorder = useDi(SSR_ACTION_RECORDER_TOKEN);
+
+  // start + env are captured once — the mode is fixed for the hook's lifetime
+  const [mode] = useState(() => {
+    const start = options.start ?? EServerActionStart.START_FROM_CLIENT;
+    const isManual = start === EServerActionStart.START_MANUAL;
+    const isServer = env === 'server';
+    // real server execution: ONLY the START_FROM_SERVER axis, and it needs the render
+    // channel's recorder; everything else on the server renders its v1 stub
+    return {
+      isManual,
+      isServer,
+      serverExecutes: isServer && start === EServerActionStart.START_FROM_SERVER && recorder !== null,
+    };
+  });
+
+  const fullId = fullServerTileId({
+    namespace: reference.namespace,
+    version: reference.version,
+    name: token.serverModuleName ?? reference.name,
+  });
+
+  // per-hook handle for manual/stub-server modes; queries go through the shared manager cache
+  // (on an executing server render too — dedup and the recorder's per-key idempotence line up)
+  const [localHandle] = useState<IServerDataHandle<TOut, TIn> | null>(() => {
+    if (mode.isServer && !mode.serverExecutes) return createServerHandle<TIn, TOut>(mode.isManual);
+    if (mode.isManual) {
+      return manager.createManual<TIn, TOut>({
+        fullId,
+        actionName: token.actionName,
+        invalidates: mergeTags(token.invalidates, options.invalidates),
+        customSerializer: token.customSerializer,
+      });
+    }
+    return null;
+  });
+
+  const key = localHandle ? null : `${fullId}/${token.actionName}#${stableStringify(options.input)}`;
+  if (key !== null) {
+    // render-phase, but idempotent by key (start-on-first-read); a new input → a new key → a new query
+    manager.ensureQuery({
+      key,
+      tags: mergeTags(token.tags, options.tags),
+      request: { fullId, actionName: token.actionName, input: options.input },
+      customSerializer: token.customSerializer,
+    });
+    // the head channel's counter waits for this query from the SAME render that started it
+    if (mode.serverExecutes) recorder!.onQueryStart(key);
+  }
+
+  const subscribe = useCallback(
+    (listener: () => void) => (localHandle ? localHandle.subscribe(listener) : manager.subscribe(key!, listener)),
+    [manager, localHandle, key],
+  );
+  const getSnapshot = useCallback(
+    () => (localHandle ? localHandle.snapshot() : manager.snapshot<TOut>(key!) as ServerData<TOut, TIn>),
+    [manager, localHandle, key],
+  );
+
+  const data = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+  if (mode.serverExecutes && key !== null) {
+    // UNCONDITIONAL suspense on an executing server render — the page waits for its data;
+    // the waiter never rejects (failures fold into an Error snapshot)
+    // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspense protocol
+    if (data.isLoading()) throw data.waiter;
+    // the retry render consumed the settled data → complete the counter + record for the cache
+    recorder!.onQuerySettled(key, data);
+  }
+
+  // opt-in suspense; never on a stub server render (its snapshot is a resolved-waiter Loading
+  // stub — throwing it would loop an async server renderer forever)
+  // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspense protocol (opt-in)
+  if (options.suspense && !mode.isServer && data.isLoading()) throw data.waiter;
+
+  return data;
+}

package/src/ssr.tsx

@@ -0,0 +1,124 @@
+// @mosetta/react/ssr — the REACT half of a server render: `export default defineSsrSide()`.
+//
+// Everything dialect-specific lives here, and nothing else does. The engine (@mosetta/server/ssr)
+// knows which artifacts enter the isolate and how they link, how the head channel counts, what a
+// preview token means and what a shell must carry; it hands all of that over as DATA. This file
+// knows how to make an element, how to hold the head open until the body settles, and how to turn
+// the result into a stream — which is react's business and no one else's.
+//
+// A page on another binding writes the same two members over the same engine. Nothing here is ever
+// imported by browser code: an ssr facet is built into the isolate grain, which is the only reason
+// react-dom/server may be named at all.
+//
+// NO JSX on purpose: the shell is built with createElement so this file reads the same way the
+// engine's contract does — a tree of data, not markup.
+import { createElement, Suspense, type FC } from 'react';
+import * as react from 'react';
+import * as jsxRuntime from 'react/jsx-runtime';
+import * as reactDom from 'react-dom/server.edge';
+import { renderToReadableStream } from 'react-dom/server.edge';
+import { createRootRenderer } from '@mosetta/server/ssr';
+import { FULL_APP_PREVIEW } from '@mosetta/runtime/client';
+import type { IShellRequest, IRootRenderer } from '@mosetta/server/ssr';
+import { isRightToLeft } from '@mosetta/core';
+
+const raw = (html: string) => ({ dangerouslySetInnerHTML: { __html: html } });
+
+/**
+ * The tags the head channel collected, held behind a boundary until the body settles: an action
+ * started deep in the tree may still add a title. Suspense-throw is the protocol both react and
+ * preact/compat understand — which is why the wait is expressed this way and not with an await.
+ */
+function headTagsElement(request: IShellRequest) {
+  let settled = false;
+  const waiting = request.waitHead().then(() => {
+    settled = true;
+  });
+  const HeadTags = () => {
+    // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspense protocol
+    if (!settled) throw waiting;
+    // the key attribute lets the browser twin (DomHeadWriter) UPSERT over these tags
+    return request.headTags().map(([key, entry]) => createElement(entry.tag, {
+      key,
+      'data-mosetta-head-key': key,
+      ...entry.attributes,
+      ...(entry.html !== undefined ? raw(entry.html) : {}),
+    }));
+  };
+  return createElement(Suspense, { fallback: null }, createElement(HeadTags, null));
+}
+
+/** the `<html>` shell: boot data in, an element tree out */
+function shellElement(request: IShellRequest) {
+  const { envelope, boot, preview } = request;
+  const base = envelope.hostBase;
+  // a link of another code source is absolute already (ADR-0070); the host's are under its base
+  const bootUrlOf = (at: string, path: string): string => (/^[a-z][a-z0-9+.-]*:/i.test(path) ? path : `${at}${path}`);
+  // the page's own words in the head (react escapes them): the title a tab and a search result
+  // show, the description a result shows under it; the rest of the head is the SEO feature's
+  const meta = (envelope as { meta?: { title?: unknown; description?: unknown } }).meta;
+  const title = typeof meta?.title === 'string' && meta.title ? meta.title : 'mosetta';
+  const description = typeof meta?.description === 'string' && meta.description ? meta.description : null;
+  // #pageContent and the boot scripts are NOT here: the engine appends them at the end of <body>
+  // once the render finished, so the envelope carries what every node declared it ships
+  // (useShippedSettings) — see the engine's withBootTail
+  // the root gets the envelope as its tree and the channel in its props — head writes and action
+  // counting from anywhere below reach the engine's per-request channel that way
+  // a PREVIEW is a preview on the server too: the realm mark below reaches only the browser's
+  // container, so the root's prop says it here — blocks that branch on previewness (a hint for
+  // an empty list, a placeholder for an analytics script) render the same html the client
+  // hydrates against
+  const Root = request.app?.Component as FC<{ moduleTreeNode: unknown; ssrChannel: unknown; preview?: { type: string } }> | undefined;
+  const appElement = Root
+    ? createElement(Root, { moduleTreeNode: envelope, ssrChannel: request.channel, ...(preview ? { preview: { type: FULL_APP_PREVIEW } } : {}) })
+    : null;
+  const lang = (envelope as { route?: { lang?: unknown } }).route?.lang;
+  // a right-to-left language lays the whole page out mirrored
+  return createElement(
+    'html',
+    typeof lang === 'string' && lang ? { lang, ...(isRightToLeft(lang) ? { dir: 'rtl' } : {}) } : null,
+    createElement(
+      'head',
+      null,
+      createElement('meta', { charSet: 'utf-8' }),
+      createElement('meta', { name: 'viewport', content: 'width=device-width, initial-scale=1' }),
+      createElement('title', null, title),
+      ...(description ? [createElement('meta', { name: 'description', content: description })] : []),
+      createElement('style', raw('html,body,#root{margin:0;padding:0}')),
+      // the declared browser closure: warm the whole artifact wave during parsing (systemjs loads
+      // via script injection → classic-script destination, `as="script"`)…
+      // SRI: cross-origin integrity requires CORS → crossorigin=anonymous
+      ...boot.preloadPaths.map((l) => createElement('link', { rel: 'preload', as: 'script', href: bootUrlOf(base, l.path), ...(l.integrity ? { integrity: l.integrity, crossOrigin: 'anonymous' } : {}) })),
+      // …and the css of EVERY styled non-lazy tree module — client-rendered parts included; fetched
+      // with CORS, hash or not, so the copy the browser keeps carries the CDN's CORS headers and a
+      // later CORS read of the same file is answered from it
+      ...boot.stylePaths.map((l) => createElement('link', { rel: 'stylesheet', href: bootUrlOf(base, l.path), crossOrigin: 'anonymous', ...(l.integrity ? { integrity: l.integrity } : {}) })),
+      headTagsElement(request),
+      // the flag must exist BEFORE any boot script runs — BlueprintRoot reads it to wrap the tree
+      // in ProvidePreview (the whole iframe realm is a preview)
+      preview ? createElement('script', raw('window.__mosettaPreview=true')) : null,
+    ),
+    createElement('body', null, createElement('div', { id: 'root' }, appElement)),
+  );
+}
+
+export function defineSsrSide(): IRootRenderer {
+  return createRootRenderer({
+    // what client artifacts link against instead of their own react family: every composed
+    // version collapses onto these. react-dom/client is named because client artifacts import
+    // hydrateRoot at the top level and only CALL it when mounting — never on the server.
+    substitutions: {
+      react: react,
+      'react/jsx-runtime': jsxRuntime,
+      'react-dom': reactDom,
+      'react-dom/client': reactDom,
+    },
+    async renderShell(request: IShellRequest): Promise<ReadableStream> {
+      const stream = await renderToReadableStream(shellElement(request), { signal: request.signal });
+      // buffered mode: await allReady before a byte is read — a late-resolving head boundary
+      // would otherwise ship as a fallback plus a patch script
+      await stream.allReady;
+      return stream;
+    },
+  });
+}

package/src/start.ts

@@ -0,0 +1,79 @@
+// @mosetta/runtime/react — the react-specific start surface: how a tree gets PUT somewhere.
+//
+// Two callers, one implementation. A page boots through its script facet, which is a one-liner
+// over `startAndMount()`; a HOST (the editor showing a block, a panel showing a form) has an
+// element and a tree and asks the root module to mount it there. Rendering a distribution must
+// not require being the page — see ADR-0034.
+//
+// react lives HERE so the `/bootstrap` core stays package-agnostic; as a script facet dependency
+// these imports are externalized like any module's — the SHARED react instance, never a bundled
+// second copy (the hooks dispatcher of a bundled react-dom would not be the one the tree's
+// modules read).
+import { createElement, type FC } from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { start } from '@mosetta/runtime/bootstrap';
+import type { IBlueprintNode } from '@mosetta/core';
+import type { IMountHandle, IMountOptions, IRootComponentSide, IRootComponentProps } from '@mosetta/react';
+import { DefaultRootComponent } from '@mosetta/react';
+
+const MOUNTED = '__mosettaMounted__';
+
+/**
+ * HYDRATION, always — including into an element with nothing in it.
+ *
+ * An empty container is not a special case: the first client render is the MIRROR PASS, where a
+ * node the server did not render returns a hole. A tree handed over by a host carries no
+ * server-render stamp at all, so every node is a hole, so the first pass produces exactly the
+ * nothing that is already there — and the holes fill in after mount. One code path for a page
+ * that arrived with server HTML and for a panel that arrived empty.
+ */
+export function reactRoot(Component: FC<IRootComponentProps>): IRootComponentSide {
+  return {
+    Component,
+    mount(element: HTMLElement, options: IMountOptions): IMountHandle {
+      const app = (tree: IBlueprintNode) => createElement(Component, { moduleTreeNode: tree, parentDi: options.parentDi, preview: options.preview });
+      const root = hydrateRoot(element, app(options.tree));
+      return {
+        // the new tree travels as a prop; the root passes it to its page manager, which is what
+        // everything under it actually reads (ADR-0033 §7)
+        render: (tree) => root.render(app(tree)),
+        unmount: () => root.unmount(),
+      };
+    },
+  };
+}
+
+/** the root a page gets without writing one: DI birth + children, and the mounting to match */
+export const defaultReactRoot = reactRoot(DefaultRootComponent);
+
+/**
+ * `start()` + mount of the page's own root module. Idempotent: two mounting script facets on one
+ * page is an authoring error — the second call warns and skips.
+ *
+ * The root mounts ITSELF: `defineRootComponentSide(defaultReactRoot)` is what an app's root
+ * module says, and the same member serves a host that wants this tree somewhere else. react-dom
+ * riding into the root's closure costs the server nothing — the isolate substitutes the react
+ * family at link time and no longer composes its artifacts (server closure.ts).
+ */
+export async function startAndMount(): Promise<void> {
+  const g = globalThis as Record<string, unknown>;
+  if (g[MOUNTED]) {
+    console.warn('[mosetta] startAndMount: page already mounted — skipped (one mounting script facet per page)');
+    return;
+  }
+  g[MOUNTED] = true;
+
+  const boot = await start();
+  if (!boot) return; // start() already reported the fatal
+  const root = boot.tree.reference ? boot.holder.getModule(boot.tree.reference) : undefined;
+  const module = root?.module as IRootComponentSide | undefined;
+  if (module?.Component == null) {
+    console.error('[mosetta] startAndMount: root module has no Component export');
+    boot.rootEl.textContent = '[mosetta] runtime failed: root module has no Component export';
+    return;
+  }
+  const mount = module.mount ?? reactRoot(module.Component).mount;
+  // the boot envelope is a page tree with extras (catalog, host base, ssr stamp) — a superset of
+  // what a mount needs
+  mount(boot.rootEl, { tree: boot.tree as unknown as IBlueprintNode });
+}

package/src/utils/ProvidedContext.tsx

@@ -0,0 +1,54 @@
+// THE context wrapper — the one implementation of the Provide/use pair. The binding keeps
+// exactly TWO contexts (the DI container and the node pointer); anything that ever needs another
+// goes through this class, so every context has a NAME and a hard edge: reading it outside a
+// provider is a named error at the read site, never an `undefined` that crashes three calls
+// later. No more hand-rolled createContext pairs, each fragile in its own way.
+import { createContext, ReactNode, useContext, useMemo } from 'react';
+import type { FC } from 'react';
+
+interface IBox<T> {
+  readonly value: T;
+}
+
+export class ProvidedContext<T> {
+  /** the provider component; carries the context's name as its displayName (devtools show it) */
+  readonly Provide: FC<{ value: T; children?: ReactNode }>;
+
+  /** the reader; throws a NAMED error when no provider is above */
+  readonly use: () => T;
+
+  /** the tolerant reader — null when no provider is above, for contexts with a sane fallback */
+  readonly useOptional: () => T | null;
+
+  constructor(name: string) {
+    // the BOX keeps `undefined` and `null` legal values — only a missing provider reads as null
+    const context = createContext<IBox<T> | null>(null);
+    context.displayName = name;
+
+    function Provide({ value, children }: { value: T; children?: ReactNode }) {
+      const box = useMemo<IBox<T>>(() => ({ value }), [value]);
+      return <context.Provider value={box}>{children}</context.Provider>;
+    }
+
+    // synthetic on purpose (one Provide per instance), so the name is stated explicitly —
+    // the convention for every component a factory builds
+    Provide.displayName = `${name}.Context`;
+
+    function use(): T {
+      const box = useContext(context);
+      if (box === null) {
+        throw new Error(`context "${name}" is not provided here — the tree above is missing its Provide`);
+      }
+      return box.value;
+    }
+
+    function useOptional(): T | null {
+      const box = useContext(context);
+      return box === null ? null : box.value;
+    }
+
+    this.Provide = Provide;
+    this.use = use;
+    this.useOptional = useOptional;
+  }
+}

package/src/utils/definers.ts

@@ -0,0 +1,190 @@
+import type { IBlueprintNode } from '@mosetta/core';
+import type { IMountPreview, IRefProviderDeclaration, ISsrRenderChannel, TBindableType } from '@mosetta/runtime/client';
+import type { Constructable, DiContainer } from '@mosetta/di';
+import type { FC } from 'react';
+
+export interface IWithComponent<T = {}> {
+  readonly Component: FC<T>;
+}
+
+export interface IComponentSide<TSettings> extends IWithComponent {
+  readonly defaultSettings: () => TSettings;
+  /**
+   * This block HANDS OUT values other blocks' settings may reference (`{ "$ref": "<name>/<key>" }`):
+   * a name and a pure adapter over this block's own settings. The page resolves references with
+   * it while rendering, the editor reads and writes through it.
+   */
+  readonly provides?: IRefProviderDeclaration<TSettings>;
+  /**
+   * The settings of this block that MAY hold a reference instead of a literal — the visible
+   * contract a provider's editor relies on when it binds a page's fields — each with the TYPE of
+   * what it holds: `{ text: 'text', href: 'url' }`. A provider of that type is offered for the
+   * field and takes it under its wing in bulk or automatically (i18n links the texts, never an
+   * address). The list form (`['text']`) still works: settings of no declared type, bindable by
+   * hand only.
+   */
+  readonly bindable?: readonly (keyof TSettings & string)[] | Readonly<Partial<Record<keyof TSettings & string, TBindableType>>>;
+  /**
+   * This block's editor facet has a part for the PAGE (`<PageInspector>` — i18n's language, a
+   * theme's pick for the canvas): the editor mounts it among the canvas tools, with the node's
+   * settings as `subject`. A block that `provides` references has one implied.
+   */
+  readonly editorChrome?: boolean;
+}
+
+/**
+ * How a block asks to be SHOWN before it is placed (the palette's hover preview) — as DATA, so
+ * that showing it never requires being written in the host's framework.
+ *
+ * - `'self'` — "me, with my own default settings"; the common answer, and one word long.
+ * - a tree — anything richer: the block with children, inside a wrapper, or under a root module
+ *   of its own (`reference`) which is free to register whatever services the specimen needs.
+ *
+ * No declaration, no preview: a block rendered alone out of any composition is a guess, and a
+ * guess shown as "this is what you are about to place" is worse than no answer.
+ */
+export type TPreviewSpec = 'self' | IPreviewTree;
+
+export interface IPreviewTree {
+  /** root module to mount the specimen with; omitted → the host's own */
+  readonly reference?: string;
+  readonly children: readonly IBlueprintNode[];
+}
+
+/**
+ * One named state of a block worth seeing — "Primary", "Without a description", "Three columns".
+ * The workbench shows every variant of a block side by side, live, on the block's own page, and
+ * opens any of them in its playground (the block's real settings form, nothing saved).
+ */
+export interface IBlockVariant<TSettings = Record<string, unknown>> {
+  /** what the variant is called, short */
+  readonly name: string;
+  /** a sentence on what it is for */
+  readonly description?: string;
+  /** settings over the block's `defaultSettings()` */
+  readonly settings?: Partial<TSettings>;
+  /**
+   * What the block holds — a container's blocks, each in its slot. Left out: what the Default
+   * variant holds (the block as `preview` declares it, or nothing).
+   */
+  readonly children?: readonly IBlueprintNode[];
+}
+
+export interface IEditorSide<TSettings = Record<string, unknown>> extends IWithComponent {
+  readonly preview?: TPreviewSpec;
+  /**
+   * DI services that arrange the SPECIMEN's environment so the LIVE component can render — a
+   * seeded editing session, a canned data source. Registered into the preview application's
+   * container before anything renders. A preview is the real component in an arranged world:
+   * these mock its surroundings, never its markup.
+   */
+  readonly previewServices?: readonly Constructable[];
+  /**
+   * The block's VARIANTS — its states worth seeing side by side, as data. "Default" (the block as
+   * it is placed) needs no entry: it always comes first.
+   */
+  readonly variants?: readonly IBlockVariant<TSettings>[];
+  /**
+   * Settings written for an EARLIER version of the block (`from`, `1.2.0`), as this version reads
+   * them — called when an author updates a block on a page. Without it, the settings move as they
+   * are, and what this version added comes from its `defaultSettings()`.
+   */
+  readonly upgrade?: (settings: Record<string, unknown>, from: string) => Partial<TSettings>;
+}
+
+export interface IFallbackSide<TSettings> extends IComponentSide<TSettings> {
+}
+
+// NO di prop (SSR epic): the container is born INSIDE the Component —
+// `useState(() => createAppContainer(...))` — so the same code path serves browser and server,
+// and a cached server isolate gets a fresh container per request for free.
+export interface IRootComponentProps {
+  moduleTreeNode: IBlueprintNode;
+  /** the mounting application's container (see IMountOptions.parentDi); absent for a page's own boot */
+  readonly parentDi?: DiContainer;
+  /** the host's word that this application is a specimen (see IMountOptions.preview) */
+  readonly preview?: IMountPreview;
+  // stamped by the ssr module during a server render, absent in the browser;
+  // the root passes the WHOLE props object into createAppContainer so the channel rides along
+  readonly ssrChannel?: ISsrRenderChannel;
+}
+
+/** what a host hands over when it asks for a tree to be put somewhere */
+export interface IMountOptions {
+  /** an ordinary page document: the root's chrome plus its children */
+  readonly tree: IBlueprintNode;
+  /**
+   * The mounting application's own container — the Unity-editor door (PARENT_DI_TOKEN in the
+   * mounted app). A mount is same-realm by construction (it takes a live element) and tokens
+   * are string-keyed, so the door survives foreign package copies and foreign bindings; what a
+   * host means to EXPOSE it registers under a named token in this container (the settings
+   * draft), and everything else is the parent environment, deliberately open at editor time.
+   */
+  readonly parentDi?: DiContainer;
+  /**
+   * The host's word that this application is a SPECIMEN — addressed to the mounted CONTAINER
+   * (the type feeds PREVIEW_TYPE_TOKEN; the services are DI classes arranging the specimen's
+   * environment).
+   */
+  readonly preview?: IMountPreview;
+}
+
+export interface IMountHandle {
+  /** put a different tree in the same application, without building it again */
+  render(tree: IBlueprintNode): void;
+  unmount(): void;
+}
+
+// The ROOT component module: an ordinary component facet whose Component is the page
+// tree's root (chrome around the tree; DI is born inside it) — and, optionally, the way to PUT
+// that tree somewhere.
+//
+// `mount` exists because rendering a distribution must not require being the page: a host (the
+// editor previewing a block, a panel showing a settings form) has an element and a tree, and asks
+// the root — the only thing that knows how to render its own tree — to do it. The page's own boot
+// goes through the very same call, from the script facet.
+//
+// It is NOT filled in by the definer: this file is imported by every component facet, and a react
+// implementation would drag react-dom into the closure of every block. The react binding hands out
+// a ready pair instead — `defineRootComponentSide(defaultReactRoot)`, or `reactRoot(MyChrome)`
+// for a root with its own chrome.
+//
+// Required, not optional: a half-contract ("some roots can be hosted") would leave every host
+// guessing. The server render pays nothing for it — the isolate substitutes the react family at
+// link time and no longer composes its artifacts at all (server closure.ts).
+export interface IRootComponentSide {
+  Component: FC<IRootComponentProps>;
+  mount: (element: HTMLElement, options: IMountOptions) => IMountHandle;
+}
+
+export function defineRootComponentSide(module: IRootComponentSide) {
+  return module;
+}
+
+export function defineComponentSide<TSettings>(module: IComponentSide<TSettings>) {
+  return module;
+}
+
+export function defineEditorSide<TSettings = Record<string, unknown>>(module: IEditorSide<TSettings>) {
+  return module;
+}
+
+export function defineFallbackSide<TSettings>(module: IFallbackSide<TSettings>) {
+  return module;
+}
+
+/**
+ * Marks a module INTERNAL: a block of the tooling (an editor panel, the workbench shell, a preview
+ * agent, the editor's own fallback) that the platform's pages place but no author should be
+ * offered — the block picker leaves it out. Wraps any definer's result, so a component and a
+ * fallback are marked the same way:
+ *
+ *   export default markInternalTile(defineComponentSide({ ... }));
+ *
+ * Merely importing the marker is the declaration: the build stamps the module `internal` by the
+ * import the facet made, the way it stamps a page root. The module itself is untouched.
+ */
+export function markInternalTile<TModule>(module: TModule): TModule {
+  return module;
+}
+