@threadlabs/looma 0.2.20 → 0.3.1

package/dist/declarative.d.cts

@@ -1,5 +1,13 @@
+/** Connects behavior only while the root participates in the document. */
 declare function manageComponentLifecycle$1(element: Element, definition: unknown, options?: { props?: Record<string, unknown>; controller?: unknown }): () => void;
 
+/**
+ * The small portion of an HTML Next definition that framework adapters need.
+ *
+ * The full definition remains runtime-owned. Keeping this type structural and
+ * deliberately narrow prevents React/Vue/Svelte adapters from learning the
+ * authoring format or treating Looma's former Stencil metadata as public API.
+ */
 type ComponentDefinition = {
     readonly contract: {
         readonly tag: string;
@@ -9,19 +17,85 @@ type ComponentDefinition = {
         readonly element: string;
     };
 };
+/**
+ * Behavior paired with a declarative definition after its native root exists.
+ *
+ * Controllers receive the HTML Next host abstraction, never a Stencil
+ * instance or the legacy invocation element. Returning a disposer makes event
+ * and observer ownership explicit when a root disconnects or is reattached.
+ *
+ * @lifecycle The runtime invokes a returned disposer before reconnecting or
+ * permanently disconnecting the same native root.
+ */
 type LoomaControllerModule = {
     readonly default?: (host: unknown) => void | (() => void);
 };
+/**
+ * Definition text and optional behavior that must be registered atomically.
+ * Keeping them paired prevents a controller from resolving against a different
+ * revision of the component contract during incremental package loading.
+ */
 type LoomaAdoptionRecord = {
     readonly tag: string;
     readonly source: string;
     readonly controller?: LoomaControllerModule;
 };
-/** Registers a materialized declarative package and enables live HTML lowering. */
+/**
+ * Installs one materialized package and enables live declarative HTML.
+ *
+ * Registration has three ordered phases: publish definitions and styles,
+ * lower markup already in the document, then observe future markup. The
+ * package name is the idempotency key because facade and direct entry points
+ * may both call this function. On the server the operation is intentionally a
+ * no-op: authored HTML remains useful fallback content and hydration is a
+ * browser concern.
+ *
+ * @lifecycle Re-registering the same package name is a no-op; a later package
+ * registration replaces the document observer only after synchronous package
+ * registrations in the current turn have settled.
+ * @ownership This registry owns injected definition/style nodes and the shared
+ * observer. Framework adapters continue to own roots they mount.
+ */
 declare function registerLoomaPackage(name: string, packageRecords: readonly LoomaAdoptionRecord[], styles: string): void;
-/** Adopts a framework-owned native root without exposing the legacy invocation element. */
+/**
+ * Attaches declarative behavior to a framework-owned native root.
+ *
+ * Framework adapters render the definition's native root themselves so their
+ * reconciliation model stays authoritative. `attachRegisteredComponent` claims
+ * the root from document observation and owns prop synchronization and
+ * controller disposal for that exact root.
+ *
+ * The explicit `tag` check is a corruption guard. A generated adapter paired
+ * with the wrong definition can otherwise appear to work while applying a
+ * different component's prop and event contract.
+ *
+ * @ownership The caller owns the native root. The returned disposer owns the
+ * prop bridge and controller instance installed for this attachment.
+ * @failure A tag/definition mismatch throws before any controller is connected.
+ */
 declare function attachLoomaComponent(element: Element, definition: ComponentDefinition, tag: string, props: Record<string, unknown>): () => void;
+/**
+ * Applies a framework adapter's props to an attached root, as authored attributes would be:
+ * each defined value becomes explicit (reflected as `data-<name>`); `undefined` restores the default.
+ * Generated adapters call this on every render instead of assigning element properties.
+ * @failure A value that does not satisfy the prop's declared type throws `HR002`; unknown prop
+ * names are ignored, and a root without an attached component is left untouched.
+ */
+declare function updateComponentProps(element: Element, props: Record<string, unknown>): void;
+/**
+ * Resolves behavior from the shared package registry.
+ * Generated adapters use this lookup instead of importing controllers directly,
+ * ensuring live HTML and framework roots execute the same module instance.
+ */
 declare function controllerFor(tag: string): LoomaControllerModule | undefined;
+/**
+ * Exposes HTML Next's connection-aware lifecycle to handwritten integrations.
+ * The callback can run again after reconnection; each connection's disposer is
+ * invoked before a later connection begins.
+ *
+ * @lifecycle The runtime invokes cleanup on disconnect and before reconnecting
+ * the same root, so each connection interval has exactly one active disposer.
+ */
 declare function manageComponentLifecycle(...args: Parameters<typeof manageComponentLifecycle$1>): ReturnType<typeof manageComponentLifecycle$1>;
 
-export { type ComponentDefinition, type LoomaAdoptionRecord, type LoomaControllerModule, attachLoomaComponent, controllerFor, manageComponentLifecycle, registerLoomaPackage };
+export { type ComponentDefinition, type LoomaAdoptionRecord, type LoomaControllerModule, attachLoomaComponent, controllerFor, manageComponentLifecycle, registerLoomaPackage, updateComponentProps };

package/dist/declarative.d.ts

@@ -1,5 +1,13 @@
+/** Connects behavior only while the root participates in the document. */
 declare function manageComponentLifecycle$1(element: Element, definition: unknown, options?: { props?: Record<string, unknown>; controller?: unknown }): () => void;
 
+/**
+ * The small portion of an HTML Next definition that framework adapters need.
+ *
+ * The full definition remains runtime-owned. Keeping this type structural and
+ * deliberately narrow prevents React/Vue/Svelte adapters from learning the
+ * authoring format or treating Looma's former Stencil metadata as public API.
+ */
 type ComponentDefinition = {
     readonly contract: {
         readonly tag: string;
@@ -9,19 +17,85 @@ type ComponentDefinition = {
         readonly element: string;
     };
 };
+/**
+ * Behavior paired with a declarative definition after its native root exists.
+ *
+ * Controllers receive the HTML Next host abstraction, never a Stencil
+ * instance or the legacy invocation element. Returning a disposer makes event
+ * and observer ownership explicit when a root disconnects or is reattached.
+ *
+ * @lifecycle The runtime invokes a returned disposer before reconnecting or
+ * permanently disconnecting the same native root.
+ */
 type LoomaControllerModule = {
     readonly default?: (host: unknown) => void | (() => void);
 };
+/**
+ * Definition text and optional behavior that must be registered atomically.
+ * Keeping them paired prevents a controller from resolving against a different
+ * revision of the component contract during incremental package loading.
+ */
 type LoomaAdoptionRecord = {
     readonly tag: string;
     readonly source: string;
     readonly controller?: LoomaControllerModule;
 };
-/** Registers a materialized declarative package and enables live HTML lowering. */
+/**
+ * Installs one materialized package and enables live declarative HTML.
+ *
+ * Registration has three ordered phases: publish definitions and styles,
+ * lower markup already in the document, then observe future markup. The
+ * package name is the idempotency key because facade and direct entry points
+ * may both call this function. On the server the operation is intentionally a
+ * no-op: authored HTML remains useful fallback content and hydration is a
+ * browser concern.
+ *
+ * @lifecycle Re-registering the same package name is a no-op; a later package
+ * registration replaces the document observer only after synchronous package
+ * registrations in the current turn have settled.
+ * @ownership This registry owns injected definition/style nodes and the shared
+ * observer. Framework adapters continue to own roots they mount.
+ */
 declare function registerLoomaPackage(name: string, packageRecords: readonly LoomaAdoptionRecord[], styles: string): void;
-/** Adopts a framework-owned native root without exposing the legacy invocation element. */
+/**
+ * Attaches declarative behavior to a framework-owned native root.
+ *
+ * Framework adapters render the definition's native root themselves so their
+ * reconciliation model stays authoritative. `attachRegisteredComponent` claims
+ * the root from document observation and owns prop synchronization and
+ * controller disposal for that exact root.
+ *
+ * The explicit `tag` check is a corruption guard. A generated adapter paired
+ * with the wrong definition can otherwise appear to work while applying a
+ * different component's prop and event contract.
+ *
+ * @ownership The caller owns the native root. The returned disposer owns the
+ * prop bridge and controller instance installed for this attachment.
+ * @failure A tag/definition mismatch throws before any controller is connected.
+ */
 declare function attachLoomaComponent(element: Element, definition: ComponentDefinition, tag: string, props: Record<string, unknown>): () => void;
+/**
+ * Applies a framework adapter's props to an attached root, as authored attributes would be:
+ * each defined value becomes explicit (reflected as `data-<name>`); `undefined` restores the default.
+ * Generated adapters call this on every render instead of assigning element properties.
+ * @failure A value that does not satisfy the prop's declared type throws `HR002`; unknown prop
+ * names are ignored, and a root without an attached component is left untouched.
+ */
+declare function updateComponentProps(element: Element, props: Record<string, unknown>): void;
+/**
+ * Resolves behavior from the shared package registry.
+ * Generated adapters use this lookup instead of importing controllers directly,
+ * ensuring live HTML and framework roots execute the same module instance.
+ */
 declare function controllerFor(tag: string): LoomaControllerModule | undefined;
+/**
+ * Exposes HTML Next's connection-aware lifecycle to handwritten integrations.
+ * The callback can run again after reconnection; each connection's disposer is
+ * invoked before a later connection begins.
+ *
+ * @lifecycle The runtime invokes cleanup on disconnect and before reconnecting
+ * the same root, so each connection interval has exactly one active disposer.
+ */
 declare function manageComponentLifecycle(...args: Parameters<typeof manageComponentLifecycle$1>): ReturnType<typeof manageComponentLifecycle$1>;
 
-export { type ComponentDefinition, type LoomaAdoptionRecord, type LoomaControllerModule, attachLoomaComponent, controllerFor, manageComponentLifecycle, registerLoomaPackage };
+export { type ComponentDefinition, type LoomaAdoptionRecord, type LoomaControllerModule, attachLoomaComponent, controllerFor, manageComponentLifecycle, registerLoomaPackage, updateComponentProps };

package/dist/declarative.js

@@ -2,12 +2,14 @@ import {
   attachLoomaComponent,
   controllerFor,
   manageComponentLifecycle,
-  registerLoomaPackage
-} from "./chunk-ECJQ4YGC.js";
+  registerLoomaPackage,
+  updateComponentProps
+} from "./chunk-XDNZIKNI.js";
 import "./chunk-MLKGABMK.js";
 export {
   attachLoomaComponent,
   controllerFor,
   manageComponentLifecycle,
-  registerLoomaPackage
+  registerLoomaPackage,
+  updateComponentProps
 };