@mosetta/react 0.0.0-stage → 0.0.10

package/src/hooks/useMediaUpload.ts

@@ -0,0 +1,20 @@
+import { SingleDiToken } from '@mosetta/di';
+import { PARENT_DI_TOKEN } from '@mosetta/runtime/client';
+import { useDi } from './di';
+
+// A settings form may offer "upload a picture" or "upload a video" — but only when the HOST offers
+// a way to store one. The workbench registers an uploader under this token in its own container;
+// a form reads it through the parent chain (like the settings draft). No host, no uploader → the
+// form shows the URL field alone. The contract is a function: a File in (with the progress of a
+// long upload reported as it goes), its public URL out.
+export interface IMediaUpload {
+  upload(file: File, onProgress?: (fraction: number) => void): Promise<string>;
+}
+
+export const MEDIA_UPLOAD_TOKEN = new SingleDiToken<IMediaUpload>('MEDIA_UPLOAD_TOKEN');
+
+/** the host's uploader, or null when the form is shown by a host that has none */
+export function useMediaUpload(): IMediaUpload | null {
+  const parent = useDi(PARENT_DI_TOKEN);
+  return parent?.hasByToken(MEDIA_UPLOAD_TOKEN) ? parent.getByToken(MEDIA_UPLOAD_TOKEN) : null;
+}

package/src/hooks/usePage.ts

@@ -0,0 +1,34 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import { useDi } from './di';
+import { PAGE_MANAGER_TOKEN, PageManager } from '@mosetta/runtime/client';
+import type { IBlueprint } from '@mosetta/core';
+
+// the manager itself is framework-agnostic and lives in @mosetta/runtime;
+// this entry keeps only the react-facing hooks
+//
+// SUBSCRIBED, not read once: the page is swappable (see PageManager — live composition in the
+// editor's preview), and a reader that only sampled it would keep rendering the tree the
+// application was born with. On the server the same snapshot answers both passes, so a server
+// render is unaffected.
+export function usePageOf(manager: PageManager): IBlueprint {
+  const snapshot = useCallback(() => manager.getCurrentPage(), [manager]);
+  return useSyncExternalStore(manager.subscribe, snapshot, snapshot);
+}
+
+export function usePage(): IBlueprint {
+  return usePageOf(useDi(PAGE_MANAGER_TOKEN));
+}
+
+/**
+ * One value out of the page, for readers that need a flag rather than the tree. Subscribing to the
+ * whole page to read one field means re-rendering on every live update — including the ones that
+ * changed a node somewhere else entirely.
+ *
+ * `select` must be a stable function (module scope), and must return something comparable by
+ * Object.is: a primitive, or a value the page itself holds.
+ */
+export function usePageValue<TValue>(select: (page: IBlueprint) => TValue): TValue {
+  const manager = useDi(PAGE_MANAGER_TOKEN);
+  const snapshot = useCallback(() => select(manager.getCurrentPage()), [manager, select]);
+  return useSyncExternalStore(manager.subscribe, snapshot, snapshot);
+}

package/src/hooks/usePreviewType.ts

@@ -0,0 +1,31 @@
+// Previewness is a CONTAINER fact, not a react context: PREVIEW_TYPE_TOKEN is computed once per
+// application in createAppContainer — from the typed mount option (IMountOptions.preview — the
+// palette's bubble mounts a specimen) or from the realm mark the preview shell writes before
+// bootstrap (the canvas iframe). These are this binding's readers over it.
+//
+// `useIsPreviewMode()` answers "should I behave like a preview". A branch on it is a move of
+// necessity — substituting DATA a live backend would supply — never the default: a preview is
+// the REAL component in an arranged environment (IEditorSide.previewServices), because the
+// same mechanism will carry the storybook.
+//
+// `usePreviewType()` answers "what KIND" — for the rare module whose duty depends on the realm
+// itself: the preview bridge WORKS inside a full-app preview and is only a description card in
+// a palette specimen.
+import { DI_CONTAINER_TOKEN } from '@mosetta/di';
+import { useDi } from './di';
+import { PREVIEW_TYPE_TOKEN } from '@mosetta/runtime/client';
+import type { TPreviewType } from '@mosetta/runtime/client';
+
+export { FULL_APP_PREVIEW, PALETTE_PREVIEW } from '@mosetta/runtime/client';
+export type { IMountPreview, TPreviewType } from '@mosetta/runtime/client';
+
+export function usePreviewType(): TPreviewType | null {
+  // through the container token, not useDi(PREVIEW_TYPE_TOKEN): a container assembled by hand
+  // (a harness, a custom root) carries no registration, and that means "live", not a crash
+  const di = useDi(DI_CONTAINER_TOKEN);
+  return di.hasByToken(PREVIEW_TYPE_TOKEN) ? di.getByToken(PREVIEW_TYPE_TOKEN) : null;
+}
+
+export function useIsPreviewMode(): boolean {
+  return usePreviewType() !== null;
+}

package/src/hooks/useResolvedSettings.ts

@@ -0,0 +1,104 @@
+import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react';
+import { DI_CONTAINER_TOKEN } from '@mosetta/di';
+import {
+  findRefProvider,
+  isRefValue,
+  TILES_HOLDER_TOKEN,
+  PAGE_MANAGER_TOKEN,
+  parseRef,
+  REF_VIEWS_TOKEN,
+  resolveRefs,
+} from '@mosetta/runtime/client';
+import type { ITilesHolder, IRefProviderDeclaration, IRefTreeNode, IRefValue } from '@mosetta/runtime/client';
+import type { IRouteMatch } from '@mosetta/core';
+import { useDi } from './di';
+
+const NO_VIEWS: Readonly<Record<string, unknown>> = Object.freeze({});
+const NO_SUBSCRIPTION = () => () => {};
+
+/** what a loaded component module declares it provides; nothing for a module not loaded (yet) */
+export function declarationOf(holder: ITilesHolder | null, reference: string): IRefProviderDeclaration | null {
+  if (!holder) return null;
+  try {
+    const loaded = holder.getModule(reference) as { module?: { provides?: IRefProviderDeclaration } } | undefined;
+    return loaded?.module?.provides ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** one reference read against the tree: the provider found lexically, its adapter asked */
+export function readRef(
+  page: IRefTreeNode,
+  consumerId: string,
+  ref: IRefValue,
+  holder: ITilesHolder | null,
+  views: Readonly<Record<string, unknown>>,
+  route: IRouteMatch | null,
+): unknown {
+  const parsed = parseRef(ref.$ref);
+  if (!parsed) return undefined;
+  const found = findRefProvider(page, consumerId, parsed.name, (reference) => declarationOf(holder, reference));
+  if (!found) return undefined;
+  try {
+    return found.provides.refs.read(found.node.settings ?? {}, parsed.key, { view: views[parsed.name] ?? null, route });
+  } catch {
+    return undefined; // a provider's bug must not take the consumer down with it
+  }
+}
+
+interface IResolved {
+  readonly raw: Record<string, unknown>;
+  readonly page: unknown;
+  readonly views: unknown;
+  readonly values: readonly unknown[];
+  readonly result: Record<string, unknown>;
+}
+
+/**
+ * A node's settings with every reference replaced by the value its provider hands out.
+ * SUBSCRIBED to the page and to the editor's views: the provider is another node, and editing
+ * it (a translation typed in the editor) must reach this consumer, whose own node did not
+ * change. Settings without references come back untouched, with no subscription at all.
+ */
+export function useResolvedSettings(nodeId: string, raw: Record<string, unknown>): Record<string, unknown> {
+  const di = useDi(DI_CONTAINER_TOKEN);
+  const hasRefs = useMemo(() => Object.values(raw).some(isRefValue), [raw]);
+  const manager = di.hasByToken(PAGE_MANAGER_TOKEN) ? di.getByToken(PAGE_MANAGER_TOKEN) : null;
+  const views = di.hasByToken(REF_VIEWS_TOKEN) ? di.getByToken(REF_VIEWS_TOKEN) : null;
+  const holder = di.hasByToken(TILES_HOLDER_TOKEN) ? di.getByToken(TILES_HOLDER_TOKEN) : null;
+  const cache = useRef<IResolved | null>(null);
+
+  const subscribe = useCallback((listener: () => void) => {
+    const offPage = manager?.subscribe(listener);
+    const offViews = views?.subscribe(listener);
+    return () => {
+      offPage?.();
+      offViews?.();
+    };
+  }, [manager, views]);
+
+  const snapshot = useCallback((): Record<string, unknown> => {
+    if (!hasRefs || !manager) return raw;
+    const page = manager.getCurrentPage();
+    const viewSnapshot = views?.snapshot() ?? NO_VIEWS;
+    const last = cache.current;
+    if (last && last.raw === raw && last.page === page && last.views === viewSnapshot) return last.result;
+    const route = (page as { route?: IRouteMatch }).route ?? null;
+    const values: unknown[] = [];
+    const result = resolveRefs(raw, (ref) => {
+      const value = readRef(page, nodeId, ref, holder, viewSnapshot, route);
+      values.push(value);
+      return value;
+    });
+    // an unrelated edit elsewhere on the page must not hand this consumer a new object
+    if (last && last.raw === raw && last.values.length === values.length && last.values.every((v, i) => Object.is(v, values[i]))) {
+      cache.current = { ...last, page, views: viewSnapshot };
+      return last.result;
+    }
+    cache.current = { raw, page, views: viewSnapshot, values, result };
+    return result;
+  }, [hasRefs, manager, views, holder, raw, nodeId]);
+
+  return useSyncExternalStore(hasRefs ? subscribe : NO_SUBSCRIPTION, snapshot, snapshot);
+}

package/src/hooks/useRoute.ts

@@ -0,0 +1,19 @@
+import type { IRouteMatch } from '@mosetta/core';
+import { usePageValue } from './usePage';
+
+const selectRoute = (page: { route?: IRouteMatch }): IRouteMatch | null => page.route ?? null;
+
+/**
+ * What the request URL said to the page's route pattern: `{slug}` segments, a `{...rest}` array,
+ * captured query values. Null in a realm the server did not stamp (a bare static build).
+ */
+export function useRoute(): IRouteMatch | null {
+  return usePageValue(selectRoute);
+}
+
+/** one named parameter, or null; a rest parameter joins its segments with `/` */
+export function useRouteParam(name: string): string | null {
+  const route = useRoute();
+  const value = route?.params[name];
+  return value === undefined ? null : Array.isArray(value) ? value.join('/') : value;
+}

package/src/hooks/useRouter.ts

@@ -0,0 +1,38 @@
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import { ROUTER_TOKEN } from '@mosetta/runtime/client';
+import type { INavigateOptions, IRouter, IRouterSnapshot } from '@mosetta/runtime/client';
+import { useDi } from './di';
+
+export interface IRouterHandle {
+  /** moves happen in place here (false on the server, in a preview, in a hosted mount) */
+  readonly active: boolean;
+  /** a move is in flight */
+  readonly pending: boolean;
+  /** the address the router last moved to */
+  readonly href: string;
+  /** move to an address of the site; false when the router did not take it (the browser should) */
+  navigate(href: string, options?: INavigateOptions): Promise<boolean>;
+  /** the same, replacing the current history entry */
+  replace(href: string, options?: Omit<INavigateOptions, 'replace'>): Promise<boolean>;
+  back(): void;
+}
+
+/**
+ * The client router (ADR-0051), the way Next hands one out: `navigate` moves to another page of
+ * the site in place, `pending` says a move is in flight. Where moves do not happen in place —
+ * the server, a preview realm, a hosted mount — `active` is false and `navigate` answers false:
+ * a block that wants to go somewhere then lets the browser (or `useNavigate`, which loads whole).
+ */
+export function useRouter(): IRouterHandle {
+  const router: IRouter = useDi(ROUTER_TOKEN);
+  const snapshot = useCallback((): IRouterSnapshot => router.snapshot(), [router]);
+  const { pending, href } = useSyncExternalStore(router.subscribe, snapshot, snapshot);
+  return useMemo(() => ({
+    active: router.active,
+    pending,
+    href,
+    navigate: (target: string, options?: INavigateOptions) => router.navigate(target, options),
+    replace: (target: string, options?: Omit<INavigateOptions, 'replace'>) => router.navigate(target, { ...options, replace: true }),
+    back: () => router.back(),
+  }), [router, pending, href]);
+}

package/src/hooks/useSettingsDraft.ts

@@ -0,0 +1,110 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import { SingleDiToken } from '@mosetta/di';
+import { PARENT_DI_TOKEN } from '@mosetta/runtime/client';
+import { useDi } from './di';
+
+// The `.editor.tsx` facet contract: the HOST owns the draft of the edited node's settings, the
+// facet form reads it and mutates through `update(patch)` (shallow merge). Save and validation
+// stay host-side — a facet never talks to the content API itself.
+//
+// The draft crosses the mount boundary through the PARENT container (IMountOptions.parentDi →
+// PARENT_DI_TOKEN): the workbench registers the store under this token in ITS OWN container, and
+// the form reads it through the door. Tokens are string-keyed, so a form built against another
+// copy of the packages — or another binding entirely — resolves the same name. What follows is
+// this binding's reader; another binding writes its own.
+export const SETTINGS_DRAFT_TOKEN = new SingleDiToken<ISettingsDraftContract>('SETTINGS_DRAFT_TOKEN');
+
+/** how one setting stands against references (see useSettingsBinding) */
+export interface IFieldBinding {
+  /** the provider this field reads from; null while it holds a literal */
+  readonly provider: string | null;
+  /** the providers this node can reach — what the field could be bound to */
+  readonly providers: readonly string[];
+}
+
+/**
+ * The draft as the HOST provides it: a store, in the shape everything else in this codebase uses.
+ * The snapshot carries settings with references RESOLVED, and `update` of a field bound to a
+ * provider writes through to the provider — a form edits values, never references. The optional
+ * members are the reference-aware part; a host that knows no references leaves them out.
+ */
+/** a key a provider's scope references, and what reads it */
+export interface IScopeEntry {
+  readonly key: string;
+  /** the block and its setting: `heading · text` */
+  readonly role: string;
+  /** the nodes that read it — where to point the author (a host that does not tell leaves it out) */
+  readonly nodes?: readonly string[];
+}
+
+/** a page's words about itself, in one language */
+export interface IPageMetaWordsShape {
+  readonly title?: string;
+  readonly description?: string;
+}
+
+/** what a provider's form may read of the page's meta */
+export interface IPageMetaShape extends IPageMetaWordsShape {
+  readonly i18n?: Readonly<Record<string, IPageMetaWordsShape>>;
+}
+
+export interface ISettingsDraftContract<TSettings = Record<string, unknown>> {
+  snapshot(): TSettings;
+  subscribe(listener: () => void): () => void;
+  update(patch: Partial<TSettings>): void;
+  binding?(field: string): IFieldBinding;
+  /**
+   * The field becomes a reference to `provider`: to `key` when given (a value picked from what the
+   * provider offers), otherwise to a fresh key holding the field's current value.
+   */
+  bind?(field: string, provider: string, key?: string): void;
+  /** the field becomes a literal again, holding the value it showed in the original */
+  unbind?(field: string): void;
+  /**
+   * For a PROVIDER's own form: every literal a block in its scope declares `bindable` becomes a
+   * reference to it. Resolves with how many fields were bound.
+   */
+  bindScope?(): Promise<number>;
+  /**
+   * For a PROVIDER's own form: the keys of its values that some block in its scope references.
+   * `providerId` names another provider node than the one the draft is about — a provider's
+   * chrome in the canvas, which lives beside whatever is selected: the node of the page in the
+   * canvas being worked in, wherever the last pick happened.
+   */
+  usedKeys?(providerId?: string): readonly string[];
+  /**
+   * For a PROVIDER's own form: the keys its scope references, in the page's order, each with what
+   * reads it (`heading · text`) — what a translator is told about each string
+   */
+  outline?(providerId?: string): readonly IScopeEntry[];
+  /** a node pointed at from a form (a list of what reads a value): the editor lights it up; null — none */
+  hover?(nodeId: string | null): void;
+  /**
+   * The meta of the page being edited — null when the document is no page (a prefab). With
+   * `providerId` (a provider's chrome asking): the page in the canvas being worked in.
+   */
+  pageMeta?(providerId?: string): IPageMetaShape | null;
+  /** the page's title and description in other languages, by language code — one undoable step */
+  setPageMetaWords?(byLang: Readonly<Record<string, IPageMetaWordsShape>>): void;
+  /** the id of the node the draft is about right now — a long operation checks it did not move */
+  node?(): string | null;
+}
+
+/** the draft as a FORM consumes it — unchanged, so no facet had to be touched */
+export interface ISettingsDraft<TSettings = Record<string, unknown>> {
+  readonly draft: TSettings;
+  update(patch: Partial<TSettings>): void;
+}
+
+export function useSettingsDraft<TSettings>(): ISettingsDraft<TSettings> {
+  const parent = useDi(PARENT_DI_TOKEN);
+  const contract = parent?.hasByToken(SETTINGS_DRAFT_TOKEN)
+    ? (parent.getByToken(SETTINGS_DRAFT_TOKEN) as ISettingsDraftContract<TSettings>)
+    : undefined;
+  if (!contract) {
+    throw new Error('useSettingsDraft: no parent application provides a settings draft (an editor facet is mounted BY a workbench, which registers the draft in its own container)');
+  }
+  const snapshot = useCallback(() => contract.snapshot(), [contract]);
+  const draft = useSyncExternalStore(contract.subscribe, snapshot, snapshot);
+  return { draft, update: contract.update };
+}

package/src/hooks/useShippedSettings.ts

@@ -0,0 +1,27 @@
+import { DI_CONTAINER_TOKEN } from '@mosetta/di';
+import { SSR_RENDER_CHANNEL_TOKEN } from '@mosetta/runtime/client';
+import { useDi } from './di';
+import { useNode, useRawSettings } from './NodeContext';
+
+/**
+ * Declares what of THIS node's settings ships to the browser in the page envelope. The server
+ * renders with the full settings; the envelope is serialized after the body settled, with
+ * `transform(settings)` in this node's place. A block that holds data for every visitor but shows
+ * each one a slice of it (translations: every language stored, one language read) ships only
+ * the slice.
+ *
+ * The one rule: the result must keep everything the render READ. The browser hydrates from the
+ * envelope — a setting the render used and the transform dropped renders differently there.
+ *
+ * A declaration, not an effect: a server render runs a component again while actions resolve,
+ * and the last declaration wins. In the browser, and on a node the server did not render, it
+ * does nothing — the envelope then carries the settings as they are.
+ */
+export function useShippedSettings<TSettings>(transform: (settings: TSettings) => TSettings): void {
+  const di = useDi(DI_CONTAINER_TOKEN);
+  const { id } = useNode();
+  const settings = useRawSettings<TSettings>();
+  const channel = di.hasByToken(SSR_RENDER_CHANNEL_TOKEN) ? di.getByToken(SSR_RENDER_CHANNEL_TOKEN) : null;
+  if (!channel?.shipSettings) return;
+  channel.shipSettings(id, transform(settings) as Record<string, unknown>);
+}

package/src/hooks/useStyler.ts

@@ -0,0 +1,34 @@
+import { useRef } from 'react';
+import { STYLE_ATTRIBUTE, STYLES_SETTING, stylePartKey, stylerCss } from '@mosetta/core';
+import { useNode, useRawSettings } from './NodeContext';
+import { useAddToHead } from './useAddToHead';
+
+// The runtime half of the STYLER (the vocabulary lives in @mosetta/core): a block calls it once
+// and spreads `part('<name>')` on each element it lets users restyle. The node's overrides
+// (`settings.styles`) become one stylesheet in the head — written during render, so the server
+// ships it with the page, and rewritten when the settings change (a live edit in the editor).
+//
+//   const styler = useStyler();
+//   return <a {...styler.part('root')} className="ui-button">{label}</a>;
+
+export interface IStyler {
+  /** the attribute that makes an element the named part of this block */
+  part(name: string): Record<string, string>;
+}
+
+const headKey = (nodeId: string): string => `styler:${nodeId}`;
+
+export function useStyler(): IStyler {
+  const { id } = useNode();
+  const settings = useRawSettings<Record<string, unknown>>();
+  const addToHead = useAddToHead();
+  const css = stylerCss(id, settings?.[STYLES_SETTING]);
+  // once written, a stylesheet is kept current — cleared to empty, not left stale, when the
+  // styles go; a node that never had any writes nothing
+  const wrote = useRef(false);
+  if (css || wrote.current) {
+    addToHead(headKey(id), 'style', { 'data-mosetta-styler': id }, css);
+    wrote.current = true;
+  }
+  return { part: (name) => ({ [STYLE_ATTRIBUTE]: stylePartKey(id, name) }) };
+}

package/src/hooks/useTheme.ts

@@ -0,0 +1,189 @@
+// THE THEME CONTROL: what a theme block hands to the blocks inside it through DI — the themes
+// there are, the one that is on, and the way to switch. A theme switcher (or any block) picks one;
+// the pick is kept in the reader's browser and put on the document root, where the theme's CSS
+// reads it (see @mosetta/core theme.ts). Blocks outside any theme get null and offer nothing.
+//
+//   const theme = useTheme();
+//   theme?.select('dark');   // kept for the next visit
+//   theme?.select(null);     // back to the system's (or the default)
+import { useCallback, useSyncExternalStore } from 'react';
+import { SingleDiToken } from '@mosetta/di';
+import { activeThemeId, themeChoiceAttribute, themeStorageName } from '@mosetta/core';
+import type { IThemeSettings, TColorScheme } from '@mosetta/core';
+import { useDiOptional } from './di';
+
+export interface IThemeOption {
+  readonly id: string;
+  readonly label: string;
+  readonly scheme: TColorScheme;
+}
+
+export interface IThemeState {
+  readonly themes: readonly IThemeOption[];
+  /** the theme that is on */
+  readonly active: string;
+  /** the reader's pick; null — the theme is decided for them (the system's, or the default) */
+  readonly chosen: string | null;
+  readonly followSystem: boolean;
+}
+
+export interface IThemeControl {
+  snapshot(): IThemeState;
+  /** what the server rendered — what a block hydrates with */
+  serverSnapshot(): IThemeState;
+  subscribe(listener: () => void): () => void;
+  /** pick a theme, kept for the next visit; null — back to the system's, or the default */
+  select(id: string | null): void;
+}
+
+export const THEME_TOKEN = new SingleDiToken<IThemeControl>('THEME_TOKEN');
+
+const DARK_QUERY = '(prefers-color-scheme: dark)';
+
+/**
+ * The control a theme block owns. Until `start` it knows neither the reader's pick nor the system
+ * — exactly what a server render knows — so the first browser render agrees with the server's and
+ * hydration is clean; the head script has already put the right theme on screen meanwhile.
+ */
+export class ThemeControl implements IThemeControl {
+  private chosen: string | null = null;
+
+  /** the theme the EDITOR shows this page in (its canvas control) — never kept, never the reader's */
+  private previewed: string | null = null;
+
+  private system: TColorScheme | null = null;
+
+  private view: Window | null = null;
+
+  private state: IThemeState;
+
+  private readonly listeners = new Set<() => void>();
+
+  private stopWatching: (() => void) | null = null;
+
+  /** what the server rendered: neither the pick nor the system known */
+  private serverState: IThemeState;
+
+  constructor(private settings: IThemeSettings) {
+    this.state = this.compute();
+    this.serverState = this.state;
+  }
+
+  readonly snapshot = (): IThemeState => this.state;
+
+  /**
+   * The state a block HYDRATES with — the server's, whatever the browser knows by then: a block
+   * hydrated late (its module loaded after the theme started) would otherwise render the pick over
+   * the server's markup, and react leaves mismatched attributes as the server wrote them.
+   */
+  readonly serverSnapshot = (): IThemeState => this.serverState;
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  /** the browser this block renders in: the reader's kept pick and the system's scheme */
+  start(view: Window): void {
+    // a second start (an effect run again) replaces the first one's watch
+    this.stopWatching?.();
+    this.view = view;
+    try {
+      this.chosen = view.localStorage.getItem(themeStorageName(this.settings.storageKey));
+    } catch {
+      this.chosen = null; // storage denied (a sandboxed frame, blocked cookies)
+    }
+    const media = view.matchMedia?.(DARK_QUERY);
+    if (media) {
+      this.system = media.matches ? 'dark' : 'light';
+      const onChange = (e: MediaQueryListEvent) => {
+        this.system = e.matches ? 'dark' : 'light';
+        this.refresh();
+      };
+      media.addEventListener('change', onChange);
+      this.stopWatching = () => media.removeEventListener('change', onChange);
+    }
+    this.refresh();
+  }
+
+  /** the theme block's settings changed (an author editing them) */
+  update(settings: IThemeSettings): void {
+    this.settings = settings;
+    this.serverState = { ...this.compute(), active: activeThemeId(settings, null, null), chosen: null };
+    this.refresh();
+  }
+
+  select(id: string | null): void {
+    const known = id !== null && this.settings.themes.some((t) => t.id === id) ? id : null;
+    this.chosen = known;
+    const view = this.view;
+    if (view) {
+      const name = themeStorageName(this.settings.storageKey);
+      const attribute = themeChoiceAttribute(this.settings.storageKey);
+      try {
+        if (known) view.localStorage.setItem(name, known);
+        else view.localStorage.removeItem(name);
+      } catch {
+        // not kept — the pick still holds for this visit
+      }
+      if (known) view.document.documentElement.setAttribute(attribute, known);
+      else view.document.documentElement.removeAttribute(attribute);
+    }
+    this.refresh();
+  }
+
+  /**
+   * Show the page in this theme for the editor's canvas, or stop (null): the document root gets
+   * the theme as if the reader had picked it, but nothing is kept — the reader's own pick, if
+   * any, comes back when the preview stops.
+   */
+  preview(id: string | null): void {
+    const known = id !== null && this.settings.themes.some((t) => t.id === id) ? id : null;
+    if (known === this.previewed) return;
+    this.previewed = known;
+    const view = this.view;
+    if (view) {
+      const attribute = themeChoiceAttribute(this.settings.storageKey);
+      const shown = known ?? this.chosen;
+      if (shown) view.document.documentElement.setAttribute(attribute, shown);
+      else view.document.documentElement.removeAttribute(attribute);
+    }
+    this.refresh();
+  }
+
+  /** stops watching the system; subscribers leave by their own unsubscribe */
+  dispose(): void {
+    this.stopWatching?.();
+    this.stopWatching = null;
+  }
+
+  private compute(): IThemeState {
+    const chosen = this.chosen && this.settings.themes.some((t) => t.id === this.chosen) ? this.chosen : null;
+    return {
+      themes: this.settings.themes.map(({ id, label, scheme }) => ({ id, label, scheme })),
+      active: this.previewed ?? activeThemeId(this.settings, chosen, this.system),
+      chosen,
+      followSystem: this.settings.followSystem,
+    };
+  }
+
+  private refresh(): void {
+    const next = this.compute();
+    if (JSON.stringify(next) === JSON.stringify(this.state)) return;
+    this.state = next;
+    for (const listener of [...this.listeners]) listener();
+  }
+}
+
+const NOTHING = () => () => {};
+const NONE = () => null;
+
+/** the theme around this block, and the way to switch it — null outside any theme */
+export function useTheme(): (IThemeState & { select(id: string | null): void }) | null {
+  const control = useDiOptional(THEME_TOKEN);
+  const state = useSyncExternalStore(control?.subscribe ?? NOTHING, control?.snapshot ?? NONE, control?.serverSnapshot ?? NONE);
+  const select = useCallback((id: string | null) => control?.select(id), [control]);
+  return state ? { ...state, select } : null;
+}

package/src/hooks/useTile.tsx

@@ -0,0 +1,34 @@
+import { ILoadedTile, TILES_HOLDER_TOKEN } from '@mosetta/runtime/client';
+import { useDi } from './di';
+
+
+export function useTile<T>(reference: string): T {
+  // TODO: validate provider
+  const holder = useDi(TILES_HOLDER_TOKEN);
+  const moduleValue = holder.getModule(reference);
+
+  if (!moduleValue) {
+    // not loaded yet → if the holder can load on demand, kick it off and SUSPEND (throw the cached
+    // promise; the loader dedups so it's stable across re-renders). The nearest <Suspense> shows its
+    // fallback until it settles, then re-renders with the ILoadedTile. This is the lazy/dynamic path.
+    if (holder.loadModule) {
+      // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspense protocol: throw the promise
+      throw holder.loadModule(reference);
+    }
+    throw new Error(`Cannot find module [${reference}]`);
+  }
+
+  // A safely-loaded module carries its failure as data (load/exec error). Re-throw it so the
+  // nearest ComponentErrorHandler isolates this subtree and renders the fallback with the cause.
+  if (moduleValue.error) {
+    throw moduleValue.error;
+  }
+
+  const clientModule = moduleValue as ILoadedTile<T>;
+
+  if (!clientModule.module) {
+    throw new Error(`Cannot find module content for [${reference}]`);
+  }
+
+  return clientModule.module;
+}