@mosetta/react 0.0.0-stage → 0.0.10

package/src/hooks/NodeContext.tsx

@@ -0,0 +1,174 @@
+// THE node pointer — the second of the two contexts (with DI) that everything module-facing
+// derives from. One provider per rendered node instead of a layer cake of six — and the pointer
+// carries ONLY what never changes for a living node: its id (plus, under a fallback, the error).
+//
+// The node's DATA does not ride the context, and the reason is react's own mechanics: context
+// propagation does not stop at a nested provider of the same context, so a pointer that carried
+// the node document would re-render EVERY descendant module whenever an ancestor's document
+// changed — an edited node's untouched sibling included, which is exactly what the renderer's
+// memo economy exists to prevent. Per-node data lives in a DI-keyed store (nodeStatesOf) that
+// the renderer writes as it walks: a component re-reads it exactly when the renderer re-rendered
+// it — the memo path IS the subscription. The context never propagates at all.
+import { ReactNode, useMemo, useSyncExternalStore } from 'react';
+import type { ITileReference, IBlueprintNode } from '@mosetta/core';
+import { DI_CONTAINER_TOKEN, DiContainer } from '@mosetta/di';
+import { useDi } from './di';
+import { ProvidedContext } from '../utils/ProvidedContext';
+import { parseReference } from '../utils/tileReference';
+import { previewSlots, slotKey, SlotMarker } from '../utils/previewSlots';
+import { useResolvedSettings } from './useResolvedSettings';
+
+export interface IProvidedChild {
+  readonly slot: string;
+  readonly child: ReactNode;
+}
+
+export const DEFAULT_SLOT = 'default';
+
+export interface IWithError {
+  readonly error: Error;
+}
+
+/**
+ * A place for children, as the module DECLARES it.
+ *
+ * Slots are not declared anywhere else on purpose: a slot exists exactly when the module renders
+ * it, and not a moment earlier — that is what lets the editor offer an insertion point only where
+ * one truly is. Capacity, though, the editor cannot observe: whether a place takes one child or
+ * any number is knowledge only the module's author has. Hence the argument is REQUIRED.
+ */
+export interface IChildrenSlot {
+  /** slot name; omitted → the default slot */
+  readonly slot?: string;
+  /**
+   * How many children this place accepts — a number, or 'many' when unbounded. The editor offers
+   * an insertion point while there is room. Spelled 'many' rather than Infinity because the value
+   * travels to the editor as JSON, where Infinity does not survive.
+   */
+  readonly max: number | 'many';
+  /** how many the module needs to look right; below it publishing warns. Default 0. */
+  readonly min?: number;
+  /**
+   * How tall the editor's insertion marker should be here, in pixels. A hint, not a rule: it only
+   * affects what the EDITOR sees (markers exist under preview alone), and it is worth setting when
+   * the default block of a few pixels looks wrong in this particular place.
+   */
+  readonly markerHeight?: number;
+}
+
+export interface INodePointer {
+  readonly id: string;
+  /** present only under a fallback: what this node's own render died of */
+  readonly error?: Error;
+}
+
+/** what the renderer knows about a node while it is on screen */
+export interface INodeState {
+  readonly node: IBlueprintNode;
+  /** effective server-renderedness of this branch (SSR epic stage 4) */
+  readonly ssrRendered: boolean;
+  /** what the renderer rendered for this node's slots */
+  readonly children: readonly IProvidedChild[];
+}
+
+// Keyed BY THE CONTAINER — one store per application, found without registering anything during
+// render (a lazy WeakMap get is idempotent; a DI registration is not). The container is the
+// application's identity everywhere else too.
+const nodeStates = new WeakMap<DiContainer, Map<string, INodeState>>();
+
+export function nodeStatesOf(di: DiContainer): Map<string, INodeState> {
+  let states = nodeStates.get(di);
+  if (!states) {
+    states = new Map();
+    nodeStates.set(di, states);
+  }
+  return states;
+}
+
+const NodeContext = new ProvidedContext<INodePointer>('node');
+
+export const ProvideNode = NodeContext.Provide;
+
+export const useNode = NodeContext.use;
+
+function useNodeState(): INodeState {
+  const { id } = useNode();
+  const di = useDi(DI_CONTAINER_TOKEN);
+  const state = nodeStatesOf(di).get(id);
+  if (!state) throw new Error(`node "${id}" has a pointer but no state — was it rendered outside the tree renderer?`);
+  return state;
+}
+
+export function useComponent(): { reference: ITileReference } {
+  const reference = useNodeState().node.reference;
+  return useMemo(() => ({ reference: parseReference(reference) }), [reference]);
+}
+
+// Node settings. NO merging with defaults here:
+// defaultSettings() is an EDITOR-side seed copied into node.settings at insertion; what the tree
+// carries is complete by contract. Absent settings (a node never touched by the editor) read as {}.
+const NO_SETTINGS: Record<string, unknown> = Object.freeze({});
+
+/**
+ * The node's settings as the block uses them: a setting that REFERENCES a value another block
+ * hands out (`{ "$ref": "i18n/k3" }`) arrives as that value — a block never sees the reference.
+ */
+export function useSettings<TSettings>(): TSettings {
+  const { node } = useNodeState();
+  return useResolvedSettings(node.id, (node.settings ?? NO_SETTINGS)) as TSettings;
+}
+
+/** the node's settings exactly as the document holds them — references unresolved */
+export function useRawSettings<TSettings>(): TSettings {
+  return (useNodeState().node.settings ?? NO_SETTINGS) as TSettings;
+}
+
+/** the error a fallback renders for; undefined everywhere outside a fallback */
+export function useError(): Error | undefined {
+  return useNode().error;
+}
+
+/**
+ * The children placed into this slot. Whatever the document holds is rendered as is: `max` and
+ * `min` are a declaration for the editor, never a filter — content is never silently dropped
+ * because the code changed its mind about capacity.
+ *
+ * Under an armed preview the returned list ends with an invisible MARKER, which is how the editor
+ * learns that this slot is being rendered at all (previewSlots). Everywhere else the list holds
+ * the children and nothing more.
+ */
+/** a child as a HOST sees it: the node document beside the element the renderer made of it */
+export interface IChildEntry {
+  readonly node: IBlueprintNode;
+  readonly child: ReactNode;
+}
+
+/**
+ * EVERY child with its document — for hosts that manage content rather than lay it out (a dock
+ * arranging tabs needs each child's identity and root reference, not a slot's worth of elements).
+ * The arrays pair 1:1 by construction: the renderer builds the elements by mapping the docs.
+ */
+export function useChildEntries(): IChildEntry[] {
+  const state = useNodeState();
+  const docs = state.node.children ?? [];
+  return state.children.map((provided, index) => ({ node: docs[index], child: provided.child }));
+}
+
+export function useChildren(place: IChildrenSlot): ReactNode[] {
+  const slot = place.slot ?? DEFAULT_SLOT;
+  const { id } = useNode();
+  const provided = useNodeState().children;
+  const armed = useSyncExternalStore(previewSlots.subscribeArmed, previewSlots.isArmed, previewSlots.neverArmed);
+  const children = provided.filter((c) => c.slot === slot).map((c) => c.child);
+  if (!armed) return children;
+  return [
+    ...children,
+    <SlotMarker key={`__slot__${slotKey(id, slot)}`}
+                ownerId={id}
+                slot={slot}
+                max={place.max}
+                min={place.min ?? 0}
+                filled={children.length}
+                height={place.markerHeight} />,
+  ];
+}

package/src/hooks/clientState.ts

@@ -0,0 +1,31 @@
+// Client/hydration state WITHOUT a context: none of it is tree-scoped data.
+import { useCallback, useEffect, useRef, useSyncExternalStore } from 'react';
+import { getIsClient } from '@mosetta/runtime/client';
+
+/** a realm fact, not a render fact — constant for the life of the session */
+export function useIsClient(): boolean {
+  return getIsClient();
+}
+
+/** true until the CALLER's own mount effect has fired */
+export function useIsFirstRender(): () => boolean {
+  const first = useRef(true);
+  useEffect(() => {
+    first.current = false;
+  }, []);
+  return useCallback(() => first.current, []);
+}
+
+const subscribeNever = () => () => {};
+const yes = () => true;
+const no = () => false;
+
+/**
+ * The hydration gate: false on the server and during the hydration MIRROR PASS, true after the
+ * component mounted. The canonical useSyncExternalStore shape — react itself re-checks the
+ * snapshot after hydration and re-renders the subscriber, which is exactly what lets a HOLE (a
+ * node the server did not render) fill in even under an unchanged memoized parent.
+ */
+export function useHydrated(): boolean {
+  return useSyncExternalStore(subscribeNever, yes, no);
+}

package/src/hooks/di.tsx

@@ -0,0 +1,65 @@
+// The react adapter of the DI container: the `di` context instance — one of the binding's two
+// contexts (ProvidedContext), living in the root entry with everything that depends on it.
+// Beside it, the SCOPE context: every rendered block provides its own scope (a child of the
+// parent block's — see BlueprintNodeRenderer), and the hooks resolve tokens FROM that scope,
+// so a facility registered for a subtree (a dock panel's tab handle) is found by walking the
+// scope chain instead of by wrapping containers.
+import { DiContainer, GlobalScope, IWithDi, MultiDiToken, Scope, SingleDiToken } from '@mosetta/di';
+import { ReactNode, useCallback, useSyncExternalStore } from 'react';
+import { ProvidedContext } from '../utils/ProvidedContext';
+
+const DiContext = new ProvidedContext<DiContainer>('di');
+
+const DiScopeContext = new ProvidedContext<Scope>('diScope');
+
+export function ProvideDi({ di, children }: { children: ReactNode } & IWithDi) {
+  return <DiContext.Provide value={di}>{children}</DiContext.Provide>;
+}
+
+export function ProvideDiScope({ scope, children }: { scope: Scope; children?: ReactNode }) {
+  return <DiScopeContext.Provide value={scope}>{children}</DiScopeContext.Provide>;
+}
+
+/** the scope this place of the tree resolves from; outside any provider — the global root */
+export function useDiScope(): Scope {
+  return DiScopeContext.useOptional() ?? GlobalScope.singleton();
+}
+
+export function useDi<T>(token: SingleDiToken<T>, scope?: Scope): T;
+export function useDi<T>(token: MultiDiToken<T>, scope?: Scope): T[];
+export function useDi<T>(token: SingleDiToken<T> | MultiDiToken<T>, scope?: Scope): T | T[] {
+  const di = DiContext.use();
+  const contextScope = useDiScope();
+  const from = scope ?? contextScope;
+
+  if (SingleDiToken.isSingleToken(token)) {
+    return di.getByToken(token, from);
+  }
+
+  return di.getManyByToken(token, from);
+}
+
+/**
+ * Resolve a token that MAY be absent — the cooperation hook: a module that can use a facility of
+ * its host (a dock's layout manager, a tab handle) pulls it optionally and simply does nothing
+ * when the host provides none. `useDi` throws for a missing token because a required dependency
+ * missing is a composition error; an optional integration is not.
+ *
+ * REACTIVE by construction: the hook subscribes to the container's implementation changes, so a
+ * facility registered (or disposed) after the first render reaches the component as a re-render —
+ * no mount-order luck involved.
+ */
+export function useDiOptional<T>(token: SingleDiToken<T>, scope?: Scope): T | null {
+  const di = DiContext.use();
+  const contextScope = useDiScope();
+  const from = scope ?? contextScope;
+  const subscribe = useCallback(
+    (onChange: () => void) => di.onTokenImplementationChange(token, from, onChange),
+    [di, token, from],
+  );
+  const read = useCallback(
+    () => (di.hasByToken(token, from) ? di.getByToken(token, from) : null),
+    [di, token, from],
+  );
+  return useSyncExternalStore(subscribe, read, read);
+}

package/src/hooks/useAddToHead.ts

@@ -0,0 +1,27 @@
+import { useMemo } from 'react';
+import { useDi } from './di';
+import { HEAD_WRITER_TOKEN, IHeadWriter, RESERVED_HEAD_KEYS } from '@mosetta/runtime/client';
+
+// Modules write head tags DURING RENDER — on the server the tag must land in the per-request
+// collector before the body settles (an effect would fire after the page shipped). The write is
+// therefore idempotent by key on both sides (last-write-wins in the collector, upsert in the DOM
+// twin) — StrictMode's double render is harmless.
+// FRAMEWORK keys are reserved: a write under one is ignored with a warning — the hook is the
+// module-facing surface, the framework's own writers (the ssr recorder) bypass it.
+export function useAddToHead(): IHeadWriter['addToHead'] {
+  const writer = useDi(HEAD_WRITER_TOKEN);
+  return useMemo(() => {
+    const write = writer.addToHead.bind(writer);
+    const warned = new Set<string>();
+    return (key, tag, attributes, html) => {
+      if (RESERVED_HEAD_KEYS.has(key)) {
+        if (!warned.has(key)) {
+          warned.add(key);
+          console.warn(`[mosetta] head key "${key}" is reserved for the framework — write ignored`);
+        }
+        return;
+      }
+      write(key, tag, attributes, html);
+    };
+  }, [writer]);
+}

package/src/hooks/useEditorContracts.ts

@@ -0,0 +1,217 @@
+import { createElement, Fragment, useCallback, useRef, useSyncExternalStore } from 'react';
+import type { ReactNode } from 'react';
+import { SingleDiToken } from '@mosetta/di';
+import type { IStyleVariable } from '@mosetta/core';
+import { PARENT_DI_TOKEN } from '@mosetta/runtime/client';
+import { useDi } from './di';
+import { useSettings } from './NodeContext';
+import { SETTINGS_DRAFT_TOKEN } from './useSettingsDraft';
+import type { IFieldBinding, IPageMetaShape, IPageMetaWordsShape, IScopeEntry, ISettingsDraftContract } from './useSettingsDraft';
+
+// What a workbench exposes to the editor facets it mounts, beside the settings draft — each a
+// named token in the workbench's own container, read through the parent door, each optional:
+// a facet shown by a host that offers none simply goes without.
+
+/** a field's binding, and the two things a form may do about it */
+export interface ISettingsBinding extends IFieldBinding {
+  bind(provider: string): void;
+  unbind(): void;
+}
+
+const NO_BINDING: IFieldBinding = { provider: null, providers: [] };
+
+function useDraftContract(): ISettingsDraftContract | null {
+  const parent = useDi(PARENT_DI_TOKEN);
+  return parent?.hasByToken(SETTINGS_DRAFT_TOKEN) ? parent.getByToken(SETTINGS_DRAFT_TOKEN) : null;
+}
+
+/**
+ * How `field` of the edited node stands against references — for a form that wants to show it
+ * (a "linked to i18n" mark) or change it. Null when the host knows no references.
+ */
+export function useSettingsBinding(field: string): ISettingsBinding | null {
+  const contract = useDraftContract();
+  const last = useRef<IFieldBinding>(NO_BINDING);
+  const snapshot = useCallback(() => {
+    const next = contract?.binding?.(field) ?? NO_BINDING;
+    const prev = last.current;
+    // the store contract wants a stable object while nothing changed
+    if (prev.provider === next.provider && prev.providers.join('|') === next.providers.join('|')) return prev;
+    last.current = next;
+    return next;
+  }, [contract, field]);
+  const subscribe = useCallback((listener: () => void) => contract?.subscribe(listener) ?? (() => {}), [contract]);
+  const binding = useSyncExternalStore(subscribe, snapshot, snapshot);
+  if (!contract?.binding) return null;
+  return {
+    ...binding,
+    bind: (provider) => contract.bind?.(field, provider),
+    unbind: () => contract.unbind?.(field),
+  };
+}
+
+/** a PROVIDER form's reach over its scope; null when the host offers none */
+export interface IProviderScope {
+  bindScope(): Promise<number>;
+  usedKeys(): readonly string[];
+  /** the provider's settings as they are NOW — after an await, the render's copy is stale */
+  settings(): Record<string, unknown>;
+  /** the node the draft is about now; a long operation stops when the author picked another */
+  node(): string | null;
+  /** the referenced keys in the page's order, each with what reads it; empty when the host tells nothing */
+  outline(): readonly IScopeEntry[];
+  /** the PAGE around the provider: its meta and the way to write its words in other languages; null — no page (a prefab) */
+  page(): { meta: IPageMetaShape; setWords(byLang: Readonly<Record<string, IPageMetaWordsShape>>): void } | null;
+  /** told whenever the document changes — a block placed, a text edited anywhere in the scope */
+  subscribe(listener: () => void): () => void;
+  /** light a node up in the editor (a list pointing at what reads a value); null — none */
+  hover(nodeId: string | null): void;
+}
+
+/**
+ * A PROVIDER's reach over its scope: in its own settings form, the provider the form is about;
+ * with `providerId`, that provider node — a provider's chrome among the canvas tools, standing
+ * beside whatever is selected. Null when the host offers none.
+ */
+export function useProviderScope(providerId?: string): IProviderScope | null {
+  const contract = useDraftContract();
+  if (!contract?.bindScope || !contract.usedKeys || !contract.node) return null;
+  const { pageMeta, setPageMetaWords } = contract;
+  const usedKeys = contract.usedKeys;
+  return {
+    bindScope: contract.bindScope,
+    usedKeys: () => usedKeys(providerId),
+    settings: contract.snapshot,
+    node: contract.node,
+    outline: () => contract.outline?.(providerId) ?? [],
+    page: () => {
+      const meta = pageMeta?.(providerId) ?? null;
+      return meta && setPageMetaWords ? { meta, setWords: setPageMetaWords } : null;
+    },
+    subscribe: contract.subscribe,
+    hover: (nodeId) => contract.hover?.(nodeId),
+  };
+}
+
+/**
+ * The views the editor chose for providers, by provider name — i18n: which language is being
+ * edited. Editor state, never document: the canvas previews it, forms read and write through it.
+ */
+export interface IEditorViewsContract {
+  snapshot(): Readonly<Record<string, unknown>>;
+  subscribe(listener: () => void): () => void;
+  set(name: string, view: unknown): void;
+}
+
+export const EDITOR_VIEWS_TOKEN = new SingleDiToken<IEditorViewsContract>('EDITOR_VIEWS_TOKEN');
+
+const NO_VIEWS: Readonly<Record<string, unknown>> = Object.freeze({});
+const NO_SUBSCRIPTION = () => () => {};
+
+/** one provider's view and its setter; null when the host keeps no views */
+export function useEditorView<TView>(name: string): { view: TView | null; set(view: TView | null): void } | null {
+  const parent = useDi(PARENT_DI_TOKEN);
+  const contract = parent?.hasByToken(EDITOR_VIEWS_TOKEN) ? parent.getByToken(EDITOR_VIEWS_TOKEN) : null;
+  const snapshot = useCallback(() => contract?.snapshot() ?? NO_VIEWS, [contract]);
+  const views = useSyncExternalStore(contract?.subscribe ?? NO_SUBSCRIPTION, snapshot, snapshot);
+  if (!contract) return null;
+  return { view: (views[name] as TView | undefined) ?? null, set: (view) => contract.set(name, view) };
+}
+
+/**
+ * The project's content config (`config.json`) as the host read it — which languages its
+ * addresses serve, and whatever else a project-wide block wants to know. Null until read, or
+ * when the host offers none.
+ */
+export interface IProjectConfigContract {
+  snapshot(): Readonly<Record<string, unknown>> | null;
+  subscribe(listener: () => void): () => void;
+}
+
+export const EDITOR_PROJECT_CONFIG_TOKEN = new SingleDiToken<IProjectConfigContract>('EDITOR_PROJECT_CONFIG_TOKEN');
+
+export function useProjectConfig(): Readonly<Record<string, unknown>> | null {
+  const parent = useDi(PARENT_DI_TOKEN);
+  const contract = parent?.hasByToken(EDITOR_PROJECT_CONFIG_TOKEN) ? parent.getByToken(EDITOR_PROJECT_CONFIG_TOKEN) : null;
+  const snapshot = useCallback(() => contract?.snapshot() ?? null, [contract]);
+  return useSyncExternalStore(contract?.subscribe ?? NO_SUBSCRIPTION, snapshot, snapshot);
+}
+
+/**
+ * The variables of the themes AROUND the edited node — what its styles may name instead of a
+ * literal (`var(--theme-accent)`). Inner themes override outer ones key by key. Empty where no
+ * theme is around, or when the host offers none.
+ */
+export interface IThemeVariablesContract {
+  snapshot(): readonly IStyleVariable[];
+  subscribe(listener: () => void): () => void;
+}
+
+export const EDITOR_THEME_VARIABLES_TOKEN = new SingleDiToken<IThemeVariablesContract>('EDITOR_THEME_VARIABLES_TOKEN');
+
+const NO_VARIABLES: readonly IStyleVariable[] = Object.freeze([]);
+
+export function useThemeVariables(): readonly IStyleVariable[] {
+  const parent = useDi(PARENT_DI_TOKEN);
+  const contract = parent?.hasByToken(EDITOR_THEME_VARIABLES_TOKEN) ? parent.getByToken(EDITOR_THEME_VARIABLES_TOKEN) : null;
+  const snapshot = useCallback(() => contract?.snapshot() ?? NO_VARIABLES, [contract]);
+  return useSyncExternalStore(contract?.subscribe ?? NO_SUBSCRIPTION, snapshot, snapshot);
+}
+
+/** what a `chrome` mount is about: the settings of the node whose control it is */
+export function useEditorSubject<TSettings>(): TSettings | null {
+  return useSettings<{ subject?: TSettings }>().subject ?? null;
+}
+
+/** …and that node's id — what a chrome asks its provider scope about (useProviderScope(id)) */
+export function useEditorSubjectId(): string | null {
+  return useSettings<{ subjectId?: string }>().subjectId ?? null;
+}
+
+/**
+ * Where the host mounted this editor facet: `settings` — the node's settings form; `chrome` — a
+ * provider's standing control in the corner of the canvas (i18n's language switch). The host
+ * says it in the facet node's own settings.
+ */
+export type TEditorPlacement = 'settings' | 'chrome';
+
+export function useEditorPlacement(): TEditorPlacement {
+  return useSettings<{ placement?: TEditorPlacement }>().placement ?? 'settings';
+}
+
+/**
+ * The TAB a section of a block's settings belongs to. The editor keeps the catalog — `main` (what
+ * the block is: its content, its options), `styles` (how it looks), `other` (everything else) —
+ * and shows one tab at a time; a name it does not know lands under `other`. Unnamed content is
+ * `main`. Read by the host off the DOM, as this attribute.
+ */
+export type TInspectorTab = 'main' | 'styles' | 'other' | (string & {});
+
+export const INSPECTOR_TAB_ATTRIBUTE = 'data-inspector-tab';
+
+/**
+ * WHERE an editor facet's parts go, said by wrapping them — the facet renders all of them, the
+ * host shows each where it belongs:
+ *
+ *   return <>
+ *     <BlockInspector><I18nForm /></BlockInspector>          // the selected block's settings
+ *     <BlockInspector tab="other"><Advanced /></BlockInspector> // …under a tab of their own
+ *     <PageInspector><LanguageSwitch /></PageInspector>      // the canvas tools, over the page
+ *   </>;
+ *
+ * Unwrapped content is the block's settings, as it always was. The host mounts the facet in each
+ * place on its own — a block's form exists while the block is selected, the page's controls for as
+ * long as the canvas tools are out — and asks for the page's part only of a module that declares
+ * `editorChrome`. A `tab` puts the section under that tab of the settings (no box of its own: the
+ * wrapper is `display: contents`).
+ */
+export function BlockInspector({ tab, children }: { tab?: TInspectorTab; children?: ReactNode }) {
+  if (useEditorPlacement() !== 'settings') return null;
+  return tab
+    ? createElement('div', { [INSPECTOR_TAB_ATTRIBUTE]: tab, style: { display: 'contents' } }, children)
+    : createElement(Fragment, null, children);
+}
+
+export function PageInspector({ children }: { children?: ReactNode }) {
+  return useEditorPlacement() === 'chrome' ? createElement(Fragment, null, children) : null;
+}

package/src/hooks/useForceRerender.ts

@@ -0,0 +1,29 @@
+import { useEffect, useState } from 'react';
+
+const forceRerenderCallbacks: Array<(path: string) => void> = [];
+
+export function useForceRerender(path: string) {
+  const [, setRenderCounter] = useState(0);
+
+  useEffect(() => {
+    function rerender(currentPath: string) {
+      if (path === currentPath) {
+        setRenderCounter(r => r + 1);
+      }
+    }
+
+    forceRerenderCallbacks.push(rerender);
+
+    return () => {
+      forceRerenderCallbacks.splice(forceRerenderCallbacks.indexOf(rerender), 1);
+    };
+  }, []);
+
+  return {
+    rerender(path: string) {
+      for (let setRender of forceRerenderCallbacks) {
+        setRender(path);
+      }
+    },
+  };
+}

package/src/hooks/useHref.ts

@@ -0,0 +1,67 @@
+import { useMemo } from 'react';
+import { isCurrentPath, resolveHref } from '@mosetta/core';
+import type { IHrefContext, IHrefOptions } from '@mosetta/core';
+import { useRoute } from './useRoute';
+import { useRouter } from './useRouter';
+
+// ADDRESSES WITHOUT LANGUAGE: a block names a path of the site as its author wrote it — `/blog`,
+// `blog/x`, or nothing for the page itself — and gets the address in the reader's language, or in
+// the one it asks for. Where the language goes in an address is the platform's business (the
+// scheme the server stamps into the route); no block writes it.
+//
+//   const href = useHref('/blog');                          // /ru/blog for a Russian reader
+//   const german = useHref(undefined, { lang: 'de' });      // this page in German, its query kept
+//   const narrowed = useHref(undefined, { query: { category: 'ai' } });
+
+export type { IHrefOptions } from '@mosetta/core';
+
+function useHrefContext(): IHrefContext {
+  const route = useRoute();
+  return useMemo(() => ({
+    path: route?.path ?? '/',
+    search: route?.search ?? {},
+    lang: route?.lang,
+    addressing: route?.addressing,
+  }), [route]);
+}
+
+/** the address of a path of this site (or of this page), in the reader's language or the one asked for */
+export function useHref(target?: string, options?: IHrefOptions): string {
+  return resolveHref(useHrefContext(), target, options);
+}
+
+/** the same, as a function — for a block that makes many addresses (a list, a language switcher) */
+export function useHrefBuilder(): (target?: string, options?: IHrefOptions) => string {
+  const context = useHrefContext();
+  return useMemo(() => (target?: string, options?: IHrefOptions) => resolveHref(context, target, options), [context]);
+}
+
+/**
+ * Go to a path of this site in the reader's language — in place through the client router
+ * (ADR-0051), or by a whole document load where the router is inert or does not take the address.
+ */
+export function useNavigate(): (target?: string, options?: IHrefOptions) => void {
+  const build = useHrefBuilder();
+  const router = useRouter();
+  return useMemo(() => (target?: string, options?: IHrefOptions) => {
+    const href = build(target, options);
+    void router.navigate(href).then((taken) => {
+      if (!taken && typeof window !== 'undefined') window.location.assign(href);
+    });
+  }, [build, router]);
+}
+
+/** whether a path of this site is where the reader is — exactly, or (`under`) anywhere beneath it */
+export function useIsCurrent(target: string, options: { under?: boolean } = {}): boolean {
+  return isCurrentPath(useHrefContext(), target, options.under === true);
+}
+
+/** the languages of the project and the one being read — a language switcher's business only */
+export function useLanguages(): { readonly current: string; readonly all: readonly string[] } {
+  const route = useRoute();
+  const addressing = route?.addressing;
+  return useMemo(() => ({
+    current: route?.lang ?? addressing?.defaultLanguage ?? 'en',
+    all: addressing?.languages ?? [route?.lang ?? 'en'],
+  }), [route, addressing]);
+}

package/src/hooks/useLocalStorageKey.ts

@@ -0,0 +1,57 @@
+import { useEffect, useState } from 'react';
+import { useForceRerender } from './useForceRerender';
+
+/**
+ * A value kept in the browser's local storage — an arrangement or a preference, never content.
+ *
+ * The store is taken from the WINDOW this component renders in, not from the bare global: a host
+ * may run a tree in another realm (the editor previews a block; a test drives a jsdom window it
+ * did not publish globally), and a bare `localStorage` reference is then a ReferenceError instead
+ * of a preference. Where there is no window at all — a server render — the initial value stands
+ * and nothing is written; the first client render agrees with it, so hydration is unaffected.
+ */
+function storage(): Storage | null {
+  try {
+    return typeof window === 'undefined' ? null : window.localStorage;
+  } catch {
+    return null; // a document that denies storage (sandboxed iframe, blocked cookies)
+  }
+}
+
+export function useLocalStorageKey<T>(key: string, initialValue: T) {
+  const [firstRender, setFirstRender] = useState(true);
+  const { rerender } = useForceRerender(key);
+
+  function setValueToStorage(value: T) {
+    const serialized = JSON.stringify(value);
+
+    storage()?.setItem(key, serialized);
+
+    return serialized;
+  }
+
+  function getValueFromStorage(): T {
+    let rawValue = storage()?.getItem(key);
+
+    if (!rawValue) {
+      rawValue = setValueToStorage(initialValue);
+    }
+
+    return JSON.parse(rawValue) as T;
+  }
+
+  useEffect(() => {
+    setFirstRender(false);
+    rerender(key);
+  }, []);
+
+  return {
+    value: firstRender
+      ? initialValue
+      : getValueFromStorage(),
+    setValue: (value: T) => {
+      setValueToStorage(value);
+      rerender(key);
+    },
+  };
+}