@loom-forge/forge-react 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# @loom-forge/forge-react
+
+**forge** · a camada React do construtor. Envolve um engine do
+[`@loom-forge/react`](../react/README.md) com um registry de definições, expande os componentes
+custom (pré-passo headless) e renderiza o resultado pelo compositor — que continua sem saber o
+que é um `ComponentDef`.
+
+```bash
+pnpm add @loom-forge/forge-react react
+```
+
+```tsx
+import { createForge, ForgeProvider, ForgeView } from "@loom-forge/forge-react";
+import { createTsliteBinder } from "@loom-forge/tslite";
+
+const forge = createForge({ binder: createTsliteBinder() })
+  .register("Card", CardComp)
+  .defineComponent(userCard); // a definição JSON
+
+<ForgeProvider forge={forge}>
+  <ForgeView
+    node={{ id: "u1", type: "UserCard", props: { id: "42" } }}
+    data={data}
+  />
+</ForgeProvider>;
+```
+
+| export                         | o quê                                                                                   |
+| ------------------------------ | --------------------------------------------------------------------------------------- |
+| `createForge(opts?)`           | engine do compositor + registry de definições. `register`/`defineComponent` encadeáveis |
+| `ForgeProvider` · `useForge()` | o contexto                                                                              |
+| `ForgeView`                    | `node` + `data` (+ `contexts` e `commands` do host) → expande e renderiza               |
+
+`createForge` aceita tudo que o `createEngine` aceita (`binder`, `resolver`, `planners`,
+`layoutRenderers`, `actions`, `capabilities`…), mais `requireEntryRoot`: um componente custom
+PRIVADO entrado como RAIZ degrada para `unknown` em vez de expandir.
+
+---
+
+## O boundary de estado
+
+Componente com `updates` ou `effects` é **vivo**: a expansão não o expande, emite o marcador
+`$stateful` (dado puro). Quem o materializa é este package — `createForge` registra o
+`StatefulBoundary`, que segura `useState(initState(def))` por **instância**, re-resolve o próprio
+corpo a cada mudança e roteia os eventos: **update local primeiro**, senão o `ActionPort` global.
+
+O corpo é expandido com os mesmos insumos da expansão estática: o mesmo `bodyOf` e os `updates` do
+componente, para que um alias de comando vindo de fora não reescreva um update local. O efeito
+resolve nos mesmos degraus do evento, pelo vocabulário de onde o componente montou.
+
+O boundary não intercepta a porta. A resolução marca `local` a intenção que é update DESTE
+componente, e o engine do corpo ganha `updates`, que a aplica; o resto sai pela porta do host.
+É por ser marca, e não nome, que o evento de um componente puro inlinado no corpo não alcança os
+updates de quem o compôs (ADR-016 do repo).
+
+### A cadeia de uma intenção, e o pendente (ADR-018 do repo)
+
+Tudo o que uma intenção recebe entra pelos `params`, e o autor escreve de onde: a raiz `event` é
+o valor recebido — o que o widget emitiu, o `data` da ação anterior num `then`, o `error` num
+`catch`. Os `params` são avaliados **no despacho**, sobre o escopo do render mais `event` (o
+`bind` os deixa compilados e guarda o escopo no binding); quem avalia é o mesmo binder do render.
+
+```jsonc
+"onClick": {
+  "action": "iniciar",                                   // local: set validando = true
+  "then": {
+    "action": "corretor/validar-email",                  // host, async
+    "params": { "email": "{{ state.dados.email }}" },
+    "then":  { "action": "marcar", "params": { "valido": "{{ event.valido }}" } },
+    "catch": { "action": "falhou", "params": { "motivo": "{{ event.code }}" } }
+  }
+}
+```
+
+O boundary executa a cadeia (`runIntent` do core): um update local resolve quando o estado foi
+escrito (`event` = `undefined`); um despacho ao host resolve com `data` no `then` ou falha com
+`error` no `catch` — falha de domínio ou o `UNHANDLED_ERROR` de um port que lançou. Um fluxo
+cancelado (`aborted` com sucesso) não é resultado e fica só com o host. **O host recebe todo
+resultado pelo `onActionResult`, com ou sem continuação.** Sem `catch`, a falha vai só ao host,
+como sempre foi.
+
+E o **pendente** é fato da instância, não estado que o autor escreve: o boundary guarda
+`pending[ação]` — `true` do despacho ao resultado de uma ação do host — e o expõe como raiz do
+escopo do corpo, para um `when`/`disabled` ler:
+
+```jsonc
+{
+  "type": "Button",
+  "props": {
+    "label": "{{ pending['corretor/validar-email'] ? 'Validando…' : 'Validar' }}",
+    "disabled": "{{ pending['corretor/validar-email'] }}",
+  },
+}
+```
+
+Um componente puro não tem boundary e não tem `pending`: é raiz só de quem é vivo. O efeito
+segue a mesma cadeia — `then`/`catch` valem nele, e o `event` de um efeito é `undefined`:
+
+```jsonc
+"effects": {
+  "carregar": {
+    "on": ["props.id"],
+    "action": "user/load",
+    "params": { "id": "{{ props.id }}" },
+    "then": { "action": "guardar", "params": { "nome": "{{ event.nome }}" } },
+    "catch": { "action": "falhou", "params": { "erro": "{{ event.code }}" } }
+  }
+}
+```
+
+É "carregar no mount e guardar o que carregou" sem o host reinjetar nada — e `pending["user/load"]`
+cobre o mount, então um `"{{ pending['user/load'] ? 'carregando' : state.nome }}"` mostra o
+estado certo do primeiro render ao resultado. O `cleanup` tem a cadeia dele.
+
+É por isso que estado mora na camada React e não no headless: o pré-passo captura a estrutura
+estática; quem faz viver é a view. Componentes aninhados — inclusive outros vivos — viram seus
+próprios boundaries, por recursão natural. Ver
+[forge/docs/STATE.md](../forge/docs/STATE.md).

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { ComponentType, ReactNode } from 'react';
+import { CreateEngineOptions, Engine, EngineDescriptor } from '@loom-forge/react';
+import { DefNode, CommandScope } from '@loom-forge/core';
+import { ComponentDefRegistry, ComponentDef } from '@loom-forge/forge';
+
+interface Forge {
+    /** o engine do compositor por baixo (componentes React registrados + render). */
+    engine: Engine;
+    /** definições de componente custom (JSON). */
+    componentDefs: ComponentDefRegistry;
+    /** boundary de entrada: componente custom privado como RAIZ degrada pra `unknown`. */
+    requireEntryRoot: boolean;
+    /** registra um componente React (delega ao compositor). Encadeável. */
+    register(type: string, component: ComponentType<any>, descriptor?: EngineDescriptor): Forge;
+    /** declara um componente custom em JSON. Encadeável. */
+    defineComponent(def: ComponentDef): Forge;
+}
+interface CreateForgeOptions extends CreateEngineOptions {
+    requireEntryRoot?: boolean;
+}
+declare function createForge(opts?: CreateForgeOptions): Forge;
+declare function ForgeProvider({ forge, children, }: {
+    forge: Forge;
+    children?: ReactNode;
+}): ReactNode;
+declare function useForge(): Forge;
+/** Entrada app-facing do construtor: expande os componentes custom e renderiza via o compositor. */
+declare function ForgeView({ node, data, contexts, commands, }: {
+    node: DefNode;
+    data?: unknown;
+    /** os contextos de AMBIENTE que o host provê nesta raiz (`auth`, `route`…). É a fronteira
+     *  declarada: dentro da árvore a prova de contexto é total; aqui ela depende disto. */
+    contexts?: Readonly<Record<string, unknown>>;
+    /** o vocabulário de COMANDO da aplicação — o que vale antes de qualquer sessão instalar o seu. */
+    commands?: CommandScope;
+}): ReactNode;
+
+export { type CreateForgeOptions, type Forge, ForgeProvider, ForgeView, createForge, useForge };

package/dist/index.js

@@ -0,0 +1,216 @@
+import { createContext, useContext, useMemo, useState, useEffect } from 'react';
+import { createEngine, ResolverProvider, Render, intentRuntimeOf } from '@loom-forge/react';
+import { resolveIntent, EMPTY_COMMANDS, runIntent, intentParams } from '@loom-forge/core';
+import { STATEFUL_TYPE, createComponentDefRegistry, resolveComponentTree, initState, bodyOf, compileDefinition, compileNodeOf, applyUpdate } from '@loom-forge/forge';
+import { jsx, jsxs } from 'react/jsx-runtime';
+
+// src/index.tsx
+function createForge(opts = {}) {
+  const engine = createEngine(opts);
+  engine.register(STATEFUL_TYPE, StatefulBoundary);
+  const componentDefs = createComponentDefRegistry();
+  const forge = {
+    engine,
+    componentDefs,
+    requireEntryRoot: opts.requireEntryRoot ?? false,
+    register(type, component, descriptor) {
+      engine.register(type, component, descriptor);
+      return forge;
+    },
+    /**
+     * A definição entra no registry **compilada** — árvore e o que mora fora dela (o `provides`,
+     * o `set` de um update, os `params` de um efeito).
+     *
+     * É uma vez, na entrada, em vez de uma vez por disparo: antes o `applyUpdate` e o
+     * `EffectRunner` compilavam na hora de agir, cada um com o próprio nó-fantasma. O SoT
+     * continua sendo o que o autor escreveu; isto é derivado, e memoizado por identidade.
+     */
+    defineComponent(def) {
+      componentDefs.register(
+        compileDefinition(def, compileNodeOf(engine.binder)).def
+      );
+      return forge;
+    }
+  };
+  return forge;
+}
+var ForgeContext = createContext(null);
+function ForgeProvider({
+  forge,
+  children
+}) {
+  return /* @__PURE__ */ jsx(ForgeContext.Provider, { value: forge, children: /* @__PURE__ */ jsx(ResolverProvider, { engine: forge.engine, children }) });
+}
+function useForge() {
+  const forge = useContext(ForgeContext);
+  if (!forge) throw new Error("useForge: faltou <ForgeProvider>.");
+  return forge;
+}
+function ForgeView({
+  node,
+  data,
+  contexts,
+  commands
+}) {
+  const forge = useForge();
+  const resolved = useMemo(
+    () => resolveComponentTree(
+      node,
+      {
+        registry: forge.engine.descriptors,
+        resolver: forge.engine.resolver,
+        binder: forge.engine.binder,
+        planners: forge.engine.planners,
+        defaultLayout: forge.engine.defaultLayout,
+        componentDefs: forge.componentDefs,
+        requireEntryRoot: forge.requireEntryRoot,
+        ...contexts ? { contexts } : {},
+        ...commands ? { commands } : {}
+      },
+      // as raízes do escopo do host: os dados e, se ele provê, o ambiente.
+      { data, ...contexts ? { ctx: contexts } : {} }
+    ),
+    [forge, node, data, contexts, commands]
+  );
+  return /* @__PURE__ */ jsx(Render, { node: resolved });
+}
+var EMPTY_CONTEXTS = {};
+var readPath = (scope, path) => {
+  let cur = scope;
+  for (const key of path.split(".")) {
+    if (cur == null || typeof cur !== "object") return void 0;
+    cur = cur[key];
+  }
+  return cur;
+};
+function EffectRunner({
+  effect,
+  scope,
+  dispatch
+}) {
+  const deps = effect.on.map((path) => readPath(scope, path));
+  useEffect(() => {
+    dispatch(effect, scope);
+    const cleanup = effect.cleanup;
+    if (!cleanup) return void 0;
+    return () => dispatch(cleanup, scope);
+  }, deps);
+  return null;
+}
+var pickContexts = (contexts, uses) => {
+  const out = {};
+  for (const name of uses ?? [])
+    if (name in contexts) out[name] = contexts[name];
+  return out;
+};
+function StatefulBoundary({
+  def,
+  callProps,
+  contexts,
+  commands
+}) {
+  const forge = useForge();
+  const [pending, setPending] = useState({});
+  const [state, setState] = useState(
+    () => (
+      // o `init` é avaliado UMA vez, contra `props` e `ctx` — a semântica do `useState(props.x)`.
+      initState(
+        def,
+        {
+          props: callProps,
+          ctx: pickContexts(contexts ?? EMPTY_CONTEXTS, def.context?.uses)
+        },
+        forge.engine.binder
+      )
+    )
+  );
+  const applyLocal = (name, params) => {
+    const act = def.updates?.[name];
+    if (act === void 0) return;
+    const extra = params && typeof params === "object" ? params : {};
+    setState(
+      (prev) => applyUpdate(
+        prev,
+        act,
+        { props: callProps, state: prev, params: extra },
+        forge.engine.binder
+      )
+    );
+  };
+  const inherited = contexts ?? EMPTY_CONTEXTS;
+  const updates = useMemo(() => new Set(Object.keys(def.updates ?? {})), [def]);
+  const resolved = useMemo(
+    () => resolveComponentTree(
+      // o MESMO corpo que a expansão estática vê: `provides` e `commands` do componente na raiz.
+      bodyOf(def),
+      {
+        registry: forge.engine.descriptors,
+        resolver: forge.engine.resolver,
+        binder: forge.engine.binder,
+        planners: forge.engine.planners,
+        defaultLayout: forge.engine.defaultLayout,
+        componentDefs: forge.componentDefs,
+        contexts: inherited,
+        ...commands ? { commands } : {},
+        updates,
+        // o corpo é DESTE componente: os nós dele mantêm a origem
+        component: def.component
+      },
+      // as raízes do corpo — `ctx` é a projeção do que ELE declarou usar
+      {
+        props: callProps,
+        state,
+        ctx: pickContexts(inherited, def.context?.uses),
+        pending
+      }
+    ),
+    [forge, def, callProps, state, pending, inherited, commands, updates]
+  );
+  const trigger = (intent, effectScope) => {
+    const resolved2 = resolveIntent(intent, commands ?? EMPTY_COMMANDS, updates);
+    runIntent(resolved2, void 0, {
+      ...intentRuntimeOf(localEngine),
+      params: (binding, event) => intentParams(
+        forge.engine.binder,
+        binding.scope === void 0 ? { ...binding, scope: effectScope } : binding,
+        event
+      )
+    });
+  };
+  const localEngine = {
+    ...forge.engine,
+    updates: {
+      apply: applyLocal,
+      pending: (action, flag) => setPending(
+        (prev) => prev[action] === flag ? prev : { ...prev, [action]: flag }
+      )
+    }
+  };
+  const scope = {
+    props: callProps,
+    state,
+    ctx: pickContexts(inherited, def.context?.uses),
+    pending
+  };
+  return /* @__PURE__ */ jsxs(ResolverProvider, { engine: localEngine, children: [
+    Object.entries(def.effects ?? {}).map(([name, effect]) => (
+      // a key inclui a FORMA do `on`: o React exige que o array de dependências tenha
+      // tamanho constante entre renders, e no canvas o autor edita o `on` ao vivo. Mudar o
+      // que se observa é outra assinatura — remontar é o que de fato aconteceu.
+      /* @__PURE__ */ jsx(
+        EffectRunner,
+        {
+          effect,
+          scope,
+          dispatch: trigger
+        },
+        `${name}|${effect.on.length}`
+      )
+    )),
+    /* @__PURE__ */ jsx(Render, { node: resolved })
+  ] });
+}
+
+export { ForgeProvider, ForgeView, createForge, useForge };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"names":["resolved"],"mappings":"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","file":"index.js","sourcesContent":["import {\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useState,\n  type ComponentType,\n  type ReactNode,\n} from \"react\";\nimport {\n  createEngine,\n  ResolverProvider,\n  Render,\n  intentRuntimeOf,\n  type CreateEngineOptions,\n  type Engine,\n  type EngineDescriptor,\n} from \"@loom-forge/react\";\nimport {\n  intentParams,\n  resolveIntent,\n  runIntent,\n  EMPTY_COMMANDS,\n  type DefNode,\n  type CommandScope,\n  type EventBinding,\n} from \"@loom-forge/core\";\nimport {\n  bodyOf,\n  compileDefinition,\n  compileNodeOf,\n  createComponentDefRegistry,\n  resolveComponentTree,\n  applyUpdate,\n  initState,\n  STATEFUL_TYPE,\n  type ComponentDef,\n  type ComponentDefRegistry,\n  type EffectDecl,\n} from \"@loom-forge/forge\";\n\n/* ──────────────────────────────────────────────────────────────────────────────\n   A camada React do CONSTRUTOR. `createForge` envolve um engine do compositor + um registry\n   de definições; `ForgeView` expande os componentes custom (pré-passo) e renderiza via o\n   compositor. O compositor (`createEngine`/`ResolverView`) NÃO conhece componente custom.\n   ────────────────────────────────────────────────────────────────────────────── */\n\nexport interface Forge {\n  /** o engine do compositor por baixo (componentes React registrados + render). */\n  engine: Engine;\n  /** definições de componente custom (JSON). */\n  componentDefs: ComponentDefRegistry;\n  /** boundary de entrada: componente custom privado como RAIZ degrada pra `unknown`. */\n  requireEntryRoot: boolean;\n  /** registra um componente React (delega ao compositor). Encadeável. */\n  register(\n    type: string,\n    component: ComponentType<any>,\n    descriptor?: EngineDescriptor,\n  ): Forge;\n  /** declara um componente custom em JSON. Encadeável. */\n  defineComponent(def: ComponentDef): Forge;\n}\n\nexport interface CreateForgeOptions extends CreateEngineOptions {\n  requireEntryRoot?: boolean;\n}\n\nexport function createForge(opts: CreateForgeOptions = {}): Forge {\n  const engine = createEngine(opts);\n  // o boundary dos componentes VIVOS é um componente React registrado no compositor: a expansão\n  // emite `$stateful` no lugar de um componente com `updates`, e a view o materializa aqui.\n  engine.register(STATEFUL_TYPE, StatefulBoundary);\n  const componentDefs = createComponentDefRegistry();\n  const forge: Forge = {\n    engine,\n    componentDefs,\n    requireEntryRoot: opts.requireEntryRoot ?? false,\n    register(type, component, descriptor) {\n      engine.register(type, component, descriptor);\n      return forge;\n    },\n    /**\n     * A definição entra no registry **compilada** — árvore e o que mora fora dela (o `provides`,\n     * o `set` de um update, os `params` de um efeito).\n     *\n     * É uma vez, na entrada, em vez de uma vez por disparo: antes o `applyUpdate` e o\n     * `EffectRunner` compilavam na hora de agir, cada um com o próprio nó-fantasma. O SoT\n     * continua sendo o que o autor escreveu; isto é derivado, e memoizado por identidade.\n     */\n    defineComponent(def) {\n      componentDefs.register(\n        compileDefinition(def, compileNodeOf(engine.binder)).def,\n      );\n      return forge;\n    },\n  };\n  return forge;\n}\n\nconst ForgeContext = createContext<Forge | null>(null);\n\nexport function ForgeProvider({\n  forge,\n  children,\n}: {\n  forge: Forge;\n  children?: ReactNode;\n}): ReactNode {\n  return (\n    <ForgeContext.Provider value={forge}>\n      <ResolverProvider engine={forge.engine}>{children}</ResolverProvider>\n    </ForgeContext.Provider>\n  );\n}\n\nexport function useForge(): Forge {\n  const forge = useContext(ForgeContext);\n  if (!forge) throw new Error(\"useForge: faltou <ForgeProvider>.\");\n  return forge;\n}\n\n/** Entrada app-facing do construtor: expande os componentes custom e renderiza via o compositor. */\nexport function ForgeView({\n  node,\n  data,\n  contexts,\n  commands,\n}: {\n  node: DefNode;\n  data?: unknown;\n  /** os contextos de AMBIENTE que o host provê nesta raiz (`auth`, `route`…). É a fronteira\n   *  declarada: dentro da árvore a prova de contexto é total; aqui ela depende disto. */\n  contexts?: Readonly<Record<string, unknown>>;\n  /** o vocabulário de COMANDO da aplicação — o que vale antes de qualquer sessão instalar o seu. */\n  commands?: CommandScope;\n}): ReactNode {\n  const forge = useForge();\n  const resolved = useMemo(\n    () =>\n      resolveComponentTree(\n        node,\n        {\n          registry: forge.engine.descriptors,\n          resolver: forge.engine.resolver,\n          binder: forge.engine.binder,\n          planners: forge.engine.planners,\n          defaultLayout: forge.engine.defaultLayout,\n          componentDefs: forge.componentDefs,\n          requireEntryRoot: forge.requireEntryRoot,\n          ...(contexts ? { contexts } : {}),\n          ...(commands ? { commands } : {}),\n        },\n        // as raízes do escopo do host: os dados e, se ele provê, o ambiente.\n        { data, ...(contexts ? { ctx: contexts } : {}) },\n      ),\n    [forge, node, data, contexts, commands],\n  );\n  return <Render node={resolved} />;\n}\n\nconst EMPTY_CONTEXTS: Readonly<Record<string, unknown>> = {};\n\n/** lê um caminho pontilhado (`\"props.id\"`) do escopo. Ausente → `undefined`, sem inventar. */\nconst readPath = (scope: Record<string, unknown>, path: string): unknown => {\n  let cur: unknown = scope;\n  for (const key of path.split(\".\")) {\n    if (cur == null || typeof cur !== \"object\") return undefined;\n    cur = (cur as Record<string, unknown>)[key];\n  }\n  return cur;\n};\n\n/**\n * UM efeito, num componente próprio — e isso é desenho, não estilo.\n *\n * Um `useEffect` por entrada de um mapa dentro do boundary tornaria a CONTAGEM de hooks\n * dependente do documento: editar a definição mudaria o número de hooks entre renders, que é\n * erro do React. Com um componente por efeito, keyed pelo nome, entrar e sair é montar e\n * desmontar — que é o que de fato aconteceu.\n *\n * Ele não renderiza nada: efeito é intenção, não view.\n */\nfunction EffectRunner({\n  effect,\n  scope,\n  dispatch,\n}: {\n  effect: EffectDecl;\n  scope: Record<string, unknown>;\n  /** dispara UMA intenção — e a cadeia dela — no escopo do componente. */\n  dispatch: (intent: EventBinding, scope: Record<string, unknown>) => void;\n}): ReactNode {\n  // as dependências são os VALORES nos caminhos declarados. `on: []` → só no mount, que é a\n  // convenção do React — sem dependência, não há o que reexecutar.\n  const deps = effect.on.map((path) => readPath(scope, path));\n  useEffect(() => {\n    dispatch(effect, scope);\n    const cleanup = effect.cleanup;\n    if (!cleanup) return undefined;\n    return () => dispatch(cleanup, scope);\n    // o escopo e o dispatch são lidos NO disparo; quem decide quando disparar é o `on`.\n  }, deps);\n  return null;\n}\n\n/** só o que o componente DECLAROU usar entra no `ctx` dele — provisão não vaza. */\nconst pickContexts = (\n  contexts: Readonly<Record<string, unknown>>,\n  uses: readonly string[] | undefined,\n): Record<string, unknown> => {\n  const out: Record<string, unknown> = {};\n  for (const name of uses ?? [])\n    if (name in contexts) out[name] = contexts[name];\n  return out;\n};\n\n/**\n * Boundary de um componente VIVO (`updates` ou `effects`): segura o estado local POR INSTÂNCIA\n * (`useState`), re-resolve o corpo contra as raízes `props`/`state`/`ctx` quando o estado muda, e\n * religa os eventos → updates locais (dispatch) — o que não é update local cai no `ActionPort`\n * global. É o puro/sujo no runtime.\n */\nfunction StatefulBoundary({\n  def,\n  callProps,\n  contexts,\n  commands,\n}: {\n  def: ComponentDef;\n  callProps: Record<string, unknown>;\n  /** os contextos em vigor no PONTO onde este componente foi montado — a expansão os\n   *  carrega no marcador `$stateful`, porque aqui o corpo é expandido de novo, ao vivo. */\n  contexts?: Readonly<Record<string, unknown>>;\n  /** o vocabulário de comando daquele ponto, pelo mesmo motivo. */\n  commands?: CommandScope;\n}): ReactNode {\n  const forge = useForge();\n  // o PENDENTE da instância: por ação do host, `true` do despacho ao resultado. É raiz do\n  // escopo (`pending[\"x/y\"]`), para um `when`/`disabled` ler sem update nenhum (ADR-018).\n  const [pending, setPending] = useState<Record<string, boolean>>({});\n  const [state, setState] = useState(() =>\n    // o `init` é avaliado UMA vez, contra `props` e `ctx` — a semântica do `useState(props.x)`.\n    initState(\n      def,\n      {\n        props: callProps,\n        ctx: pickContexts(contexts ?? EMPTY_CONTEXTS, def.context?.uses),\n      },\n      forge.engine.binder,\n    ),\n  );\n\n  /**\n   * Um UPDATE deste componente — escrita de estado, síncrona.\n   *\n   * Só chega aqui o que a resolução MARCOU como local (`binding.local`), e ela marca com os\n   * updates DESTE componente. O evento de um componente puro inlinado no corpo não é marcado, e\n   * sai pela porta como qualquer outro: o boundary não intercepta nada por nome.\n   */\n  const applyLocal = (name: string, params?: unknown): void => {\n    const act = def.updates?.[name];\n    // a marca veio da expansão com estes mesmos updates, então o update existe\n    if (act === undefined) return;\n    const extra = params && typeof params === \"object\" ? params : {};\n    setState((prev) =>\n      applyUpdate(\n        prev,\n        act,\n        { props: callProps, state: prev, params: extra },\n        forge.engine.binder,\n      ),\n    );\n  };\n\n  const inherited = contexts ?? EMPTY_CONTEXTS;\n  // os nomes que resolvem AQUI dentro, antes de qualquer escopo de comando: o corpo é deste\n  // componente, e um alias de fora com o mesmo nome não pode reescrever o update dele.\n  const updates = useMemo(() => new Set(Object.keys(def.updates ?? {})), [def]);\n  const resolved = useMemo(\n    () =>\n      resolveComponentTree(\n        // o MESMO corpo que a expansão estática vê: `provides` e `commands` do componente na raiz.\n        bodyOf(def),\n        {\n          registry: forge.engine.descriptors,\n          resolver: forge.engine.resolver,\n          binder: forge.engine.binder,\n          planners: forge.engine.planners,\n          defaultLayout: forge.engine.defaultLayout,\n          componentDefs: forge.componentDefs,\n          contexts: inherited,\n          ...(commands ? { commands } : {}),\n          updates,\n          // o corpo é DESTE componente: os nós dele mantêm a origem\n          component: def.component,\n        },\n        // as raízes do corpo — `ctx` é a projeção do que ELE declarou usar\n        {\n          props: callProps,\n          state,\n          ctx: pickContexts(inherited, def.context?.uses),\n          pending,\n        },\n      ),\n    [forge, def, callProps, state, pending, inherited, commands, updates],\n  );\n\n  /**\n   * O disparo de um EFEITO. Evento chega aqui já roteado pela expansão; efeito não passa por\n   * ela — então resolve aqui, pelo mesmo `resolveIntent` e na mesma ordem.\n   *\n   * O escopo é o do lugar onde o componente MONTOU: o efeito é intenção do componente, não de um\n   * nó do corpo, e o `commands` do componente instala para o corpo, não para si — como o\n   * `provides`.\n   */\n  const trigger = (\n    intent: EventBinding,\n    effectScope: Record<string, unknown>,\n  ): void => {\n    // a cadeia inteira resolve aqui — cada elo pela mesma régua da expansão —, e roda pelo mesmo\n    // runtime dos eventos: o `params` de cada elo é avaliado no despacho, sobre o escopo do\n    // componente mais `event`. O efeito não passa pelo `bind`, então o escopo entra por aqui.\n    const resolved = resolveIntent(intent, commands ?? EMPTY_COMMANDS, updates);\n    runIntent(resolved, undefined, {\n      ...intentRuntimeOf(localEngine),\n      params: (binding, event) =>\n        intentParams(\n          forge.engine.binder,\n          binding.scope === undefined\n            ? { ...binding, scope: effectScope }\n            : binding,\n          event,\n        ),\n    });\n  };\n\n  // o engine do corpo: a porta continua a do host, e a intenção MARCADA local vem para cá —\n  // e o PENDENTE também: `true` do despacho ao resultado de uma ação do host (ADR-018).\n  const localEngine: Engine = {\n    ...forge.engine,\n    updates: {\n      apply: applyLocal,\n      pending: (action, flag) =>\n        setPending((prev) =>\n          prev[action] === flag ? prev : { ...prev, [action]: flag },\n        ),\n    },\n  };\n  // o escopo dos efeitos é o MESMO do corpo — um efeito vê o que o componente vê.\n  const scope = {\n    props: callProps,\n    state,\n    ctx: pickContexts(inherited, def.context?.uses),\n    pending,\n  };\n  return (\n    <ResolverProvider engine={localEngine}>\n      {Object.entries(def.effects ?? {}).map(([name, effect]) => (\n        // a key inclui a FORMA do `on`: o React exige que o array de dependências tenha\n        // tamanho constante entre renders, e no canvas o autor edita o `on` ao vivo. Mudar o\n        // que se observa é outra assinatura — remontar é o que de fato aconteceu.\n        <EffectRunner\n          key={`${name}|${effect.on.length}`}\n          effect={effect}\n          scope={scope}\n          dispatch={trigger}\n        />\n      ))}\n      <Render node={resolved} />\n    </ResolverProvider>\n  );\n}\n"]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@loom-forge/forge-react",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "forge · a camada React do construtor: createForge/ForgeProvider/ForgeView e o boundary de estado por instância ($stateful).",
+  "keywords": [
+    "react",
+    "nocode",
+    "components",
+    "state"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Anderson D. Rosa",
+    "url": "https://github.com/andersondrosa"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/andersondrosa/loom-forge.git",
+    "directory": "packages/forge-react"
+  },
+  "homepage": "https://github.com/andersondrosa/loom-forge/tree/main/packages/forge-react#readme",
+  "bugs": {
+    "url": "https://github.com/andersondrosa/loom-forge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@loom-forge/core": "0.1.0",
+    "@loom-forge/forge": "0.1.0",
+    "@loom-forge/react": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3",
+    "@loom-forge/tslite": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}