@lightspeed-js/core 0.1.0

package/dist/types/src/marker.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Island boundaries, as comment pairs.
+ *
+ * ```html
+ * <!--lsp {"c":"chart","props":{"title":"Q"},"hydrate":"visible"}-->
+ *   …content…
+ * <!--/lsp-->
+ * ```
+ *
+ * Comments rather than a custom element because comments are legal in **every**
+ * parser insertion mode. `<lsp-mount>` inside `<tbody>` is foster-parented out
+ * of the table by the HTML parser - confirmed, not theoretical - which becomes
+ * a shipped-HTML bug the moment markers appear in static output.
+ *
+ * A pair also gives three things one element could not hold at once: rendered
+ * content, slot content, and a skeleton. Content simply lives *between* the
+ * comments as ordinary DOM.
+ */
+export interface MarkerPayload {
+    /** Component id. */
+    c: string;
+    /** Static attributes, which become props. */
+    props?: Record<string, string | true>;
+    /** Static presentational attributes, forwarded to the child's root. */
+    attrs?: Record<string, string>;
+    /** `@event="handler"`, evaluated in the parent's scope. */
+    on?: Record<string, string>;
+    /** `$name="expr"` - dynamic props, plus class/style for the root. */
+    bind?: Record<string, string>;
+    /**
+     * `$cell:name="key"` - a prop the **child** subscribes to, by cell key.
+     *
+     * Written at the usage site like a prop, delivered like a cell: nothing is
+     * evaluated in the parent's scope, so the parent is not in the propagation
+     * path and can be flattened, unmounted or never mounted at all. See ADR-053.
+     */
+    cells?: Record<string, string>;
+    /**
+     * `<Dynamic $is="expr" />` - the component is named by an expression, not by
+     * the tag.
+     *
+     * `c` is empty in this case and filled in at mount, once the expression can
+     * be evaluated against the owner's scope. Everything downstream - props,
+     * slots, `$hydrate`, `$needs` - behaves exactly as it would for a tag.
+     */
+    dyn?: string;
+    /** `$hydrate` keyword: when the logic runs. */
+    hydrate?: string;
+    /**
+     * `$needs` - the cells this usage waits on. See ADR-010.
+     *
+     * Independent of `hydrate`, which says *when* the logic runs. This says what
+     * has to be true before there is anything to render. The skeleton is the
+     * consequence, not the declaration.
+     *
+     * Present but empty is `$needs` with no value: "wait for me, I fetch
+     * internally". It names nothing resolvable, so it suppresses build rendering
+     * and imposes no runtime gate.
+     */
+    needs?: string[];
+    /** Set by the build: the content between the markers is rendered output. */
+    ssr?: number;
+}
+export declare const MARKER_END = "<!--/lsp-->";
+/**
+ * A comment may not contain `--`, so any run of dashes in the payload is
+ * escaped. `-` parses back to `-`, so the round trip is lossless.
+ */
+export declare function serializeMarker(payload: MarkerPayload): string;
+export declare function isMarkerStart(node: Node): boolean;
+export declare function isMarkerEnd(node: Node): boolean;
+export declare function parseMarker(node: Node): MarkerPayload | null;
+/**
+ * Index of the `<!--/lsp-->` closing `nodes[start]`, accounting for nesting.
+ * Returns -1 if unterminated.
+ */
+export declare function findMarkerEnd(nodes: Node[], start: number): number;
+/**
+ * The slot content for a marker.
+ *
+ * For a server-rendered island the nodes between the comments are *output*,
+ * not slot content - the original is stashed in an inert
+ * `<template data-lsp-slot>` so the client can rebuild from it.
+ */
+export declare function slotNodesFor(payload: MarkerPayload, between: Node[]): Node[];

package/dist/types/src/parser/index.d.ts

@@ -0,0 +1,2 @@
+export { parseLSP, validateLSP, inlineStyleSources } from "./lsp.js";
+export type { LSPComponent } from "./lsp.js";

package/dist/types/src/parser/layout.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Layouts - shared document structure for multi-page projects.
+ *
+ * A multi-page project repeats its doctype, head, stylesheet links, chrome and
+ * script tags in every page. A layout holds that once; pages declare which one
+ * they use and supply only their content.
+ *
+ * This is deliberately the *same* vocabulary as component slots - `<slot>`,
+ * `<slot name>`, `<template slot>`, fallback content - rather than a second
+ * composition concept to learn. The difference is only when it happens:
+ * layouts are substituted at build, so the output is what you would have
+ * written by hand and nothing about layouts survives into the page.
+ */
+export declare const LAYOUT_OPT_OUT = "none";
+/**
+ * The layout name a page asks for, or null if it does not ask.
+ *
+ * Null means "decide by convention" - not "no layout". Only an explicit
+ * `none` opts out, so a page can always escape the convention.
+ */
+export declare function readLayoutName(html: string): string | null;
+export declare function stripLayoutDeclaration(html: string): string;
+/**
+ * Substitute a page into its layout.
+ *
+ * Unfilled slots keep their fallback content, which is what makes a layout
+ * able to carry a sensible default title or empty chrome.
+ */
+export declare function applyLayout(page: string, layout: string, context?: {
+    page?: string;
+    layout?: string;
+}): string;

package/dist/types/src/parser/lsp.d.ts

@@ -0,0 +1,56 @@
+export interface LSPComponent {
+    view: string;
+    skeleton: string;
+    logic: string;
+    /** `<style>` - inlined with the page. Anything affecting size or layout. */
+    style: string;
+    /**
+     * `<style deferred>` - shipped with the component and applied when it
+     * hydrates. Hover, focus, transitions: nothing can be in those states before
+     * hydration, so they cost nothing up front.
+     */
+    styleDeferred: string;
+    /**
+     * Files a `<style src="…">` asked for, in the order they were written.
+     *
+     * Unresolved here: parsing stays pure, and reading a file is the caller's
+     * business. `inlineStyleSources` does the joining, given something that can
+     * read.
+     */
+    styleSources: string[];
+    styleDeferredSources: string[];
+    /**
+     * `<needs>` - cell keys this component cannot render without.
+     *
+     * Declared by the component rather than by every place that uses it. A
+     * caller should not have to know what its data dependencies are, and
+     * repeating the key at each usage is the same coupling a prop chain has.
+     *
+     * Read by the compiler, not at runtime: gating decides whether the logic
+     * runs at all, so it has to be knowable before the logic exists.
+     */
+    needs: string[];
+    filename: string;
+}
+/**
+ * Parse a Lightspeed Single File Component (.lsp)
+ */
+export declare function parseLSP(content: string, filename: string): LSPComponent;
+/**
+ * Fold every `<style src="…">` into the component's own styles.
+ *
+ * Shared rules are **inlined per component**, not emitted once: each copy is
+ * scoped to the component that asked for it, so sharing a file never means
+ * sharing a selector. Two components with the same rules get two scoped
+ * copies, which is what stops one of them ever styling the other's markup.
+ *
+ * Shared text comes first, so a component's own rules win. Everything is
+ * scoped with `:where()` and therefore weighs nothing, which means source
+ * order is the whole of the cascade here - "mine, after theirs" is the only
+ * override rule an author needs to know.
+ */
+export declare function inlineStyleSources(component: LSPComponent, read: (specifier: string, from: string) => string): LSPComponent;
+/**
+ * Validate that required sections exist
+ */
+export declare function validateLSP(component: LSPComponent): string[];

package/dist/types/src/parser/route.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Route patterns - `/blog/:slug`.
+ *
+ * A page declares the shape of its URL, and the build turns that into real
+ * files wherever it can enumerate the values. Nothing here does client-side
+ * navigation: links are ordinary links and every navigation is a full page
+ * load. The only thing a pattern buys is that data can live in the *path*
+ * rather than a query string.
+ */
+export interface RouteDeclaration {
+    /** Absent when the routes tree supplies it. */
+    pattern?: string;
+    /**
+     * The build-time cell holding the rows to enumerate, if any.
+     *
+     * With it, the build emits one real file per row. Without it the URLs are
+     * not knowable at build - an admin editing arbitrary entries - and the page
+     * ships as a single shell the host rewrites onto, with params read from the
+     * path at runtime.
+     */
+    from?: string;
+}
+export interface RouteSegment {
+    /** Literal text, or the parameter name when `param` is true. */
+    value: string;
+    param: boolean;
+}
+export interface ParsedRoute {
+    pattern: string;
+    segments: RouteSegment[];
+    params: string[];
+    /**
+     * Every URL matching this pattern has the same number of segments.
+     *
+     * False only for a catch-all. It matters because a rewritten page is one
+     * file answering many URLs: with a relative `base`, asset paths resolve
+     * against the URL's depth rather than the file's, so a varying depth cannot
+     * be made to work.
+     */
+    fixedDepth: boolean;
+}
+export declare function readRouteDeclaration(html: string): RouteDeclaration | null;
+export declare function stripRouteDeclaration(html: string): string;
+export declare function parseRoute(pattern: string): ParsedRoute;
+/** `/blog/:slug` + `{ slug: "post-1" }` → `/blog/post-1` */
+export declare function buildPath(route: ParsedRoute, params: Record<string, unknown>): string;
+/** `/blog/:slug` + `/blog/post-1` → `{ slug: "post-1" }`, or null. */
+export declare function matchPath(route: ParsedRoute, pathname: string): Record<string, string> | null;
+/**
+ * The file a URL is served from: `/blog/post-1` → `blog/post-1/index.html`.
+ *
+ * Directory output rather than `blog/post-1.html` so the URL carries no
+ * extension, which every static host serves without configuration.
+ */
+export declare function outputFileFor(path: string): string;
+/**
+ * How many directories deep a URL sits, which is what a relative `base`
+ * resolves asset paths against.
+ */
+export declare function depthOf(path: string): number;
+/** The directory whose tree defines a project's URLs. */
+export declare const ROUTES_DIR = "routes";
+/**
+ * The URL a page answers, from where it sits in the routes tree.
+ *
+ * `[param]` is a segment, `[...rest]` a catch-all, and a trailing `index` is
+ * the folder itself. The tree *is* the route map, so finding a page's URL is
+ * reading its path rather than opening it.
+ *
+ *   index.html                          →  /
+ *   about.html                          →  /about
+ *   blog/index.html                     →  /blog
+ *   collections/[collection]/index.html →  /collections/:collection
+ *   collections/[collection]/[id].html  →  /collections/:collection/:id
+ *   docs/[...rest].html                 →  /docs/*
+ */
+export declare function routeFromFile(relative: string): string;
+/** Does this path carry dynamic segments, or is it a fixed page? */
+export declare function isDynamicRoute(relative: string): boolean;
+/**
+ * A stable file for a runtime-resolved page.
+ *
+ * One shell answers many URLs, so it cannot live at any of them. It goes
+ * somewhere clearly internal instead, and the host rewrites onto it. Depth is
+ * irrelevant because a runtime route already requires an absolute `base`.
+ */
+export declare function shellFileFor(pattern: string): string;

package/dist/types/src/parser/style-source-node.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Read a `<style src="…">` from disk, relative to the `.lsp` that asked.
+ *
+ * Kept out of `parser/index.ts` on purpose: that module is in the graph of
+ * `lightspeed/compile`, which a consumer may bundle for a browser, and `fs`
+ * has no business travelling there. Anything with a filesystem imports this
+ * one directly.
+ *
+ * A missing file throws, naming both ends. The failure this replaces is a
+ * component compiling with its styles silently absent - which is exactly the
+ * bug that made shared styles worth having.
+ */
+export declare function nodeStyleReader(): (specifier: string, from: string) => string;
+/** Where a `<style src="…">` resolves to, for watching it. */
+export declare function styleSourcePaths(component: {
+    filename: string;
+    styleSources: string[];
+    styleDeferredSources: string[];
+}): string[];

package/dist/types/src/parser/style.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Build-time CSS scoping.
+ *
+ * Every component's styles are scoped by default: its selectors gain an
+ * attribute matching a per-component hash, and the runtime stamps that same
+ * attribute on the elements the component owns. `:global(...)` opts a part of a
+ * selector back out.
+ *
+ * No shadow DOM and no runtime cost - which is what let ADR-003 reject custom
+ * elements without giving up encapsulation.
+ */
+/** A short, stable id for a component. */
+export declare function scopeIdFor(componentId: string): string;
+export declare function scopeStyles(css: string, scopeId: string): string;
+export interface Scopes {
+    /** Zero-specificity scope for ordinary rules. */
+    normal: string;
+    /** Weighted anchor for `:deep()` overrides. */
+    deep: string;
+}

package/dist/types/src/parser/template.d.ts

@@ -0,0 +1,32 @@
+interface ComponentRegistry {
+    [key: string]: {
+        template: string;
+        style: string;
+        logic: string;
+        /** Cell keys the component itself declared - see `LSPComponent.needs`. */
+        needs?: string[];
+    };
+}
+/**
+ * Transform Lightspeed template syntax to browser-ready HTML.
+ *
+ * Child components are NOT inlined here. They become <lsp-mount> placeholders
+ * that the runtime replaces with a real, independently-stated instance. Text
+ * spliced at build time has no identity, which is what made every usage of a
+ * component share one state object.
+ */
+export declare function transformTemplate(template: string, componentId: string, componentRegistry?: ComponentRegistry): string;
+/**
+ * Extract reactive expressions from template for analysis
+ */
+export declare function extractReactiveExpressions(template: string): string[];
+/**
+ * Extract import statements from component logic for dependency tracking
+ */
+export declare function extractImports(logic: string): Array<{
+    variable: string;
+    path: string;
+    type: "default" | "named" | "star";
+}>;
+export declare function validateTemplate(template: string): string[];
+export {};

package/dist/types/src/parser/test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/runtime/bindings/BindingEvaluator.d.ts

@@ -0,0 +1,174 @@
+import type { ComponentInstance } from "../components/ComponentInstance.js";
+import type { CellManager } from "../state/index.js";
+import type { BindingHolder, ForBlock, Row } from "../dom/ForBlock.js";
+export type BindingKind = "text" | "class" | "attr" | "prop" | "model" | "for" | "show" | "html";
+type Compiled = (state: any, props: any, shared: any, pending: (key: string) => boolean, ...locals: any[]) => any;
+interface BaseBinding {
+    expr: string;
+    compiled: Compiled;
+    /** Cell keys this expression read last time it was evaluated. */
+    cellKeys?: Set<string>;
+    cellUnsubscribes?: Array<() => void>;
+    cleanupRegistered?: boolean;
+}
+export interface ElementBinding extends BaseBinding {
+    kind: "text" | "class" | "attr" | "show" | "html";
+    el: Element;
+    /** Target attribute name, for kind "attr". */
+    attr?: string;
+}
+/**
+ * A binding whose target is a child component's prop rather than an element.
+ * Owned by the parent and evaluated in the parent's scope.
+ */
+export interface PropBinding extends BaseBinding {
+    kind: "prop";
+    target: ComponentInstance;
+    name: string;
+}
+export interface ModelTarget {
+    /** DOM *property* - not an attribute. */
+    prop: "value" | "checked";
+    event: string;
+    coerce: (raw: any) => any;
+    radio?: boolean;
+}
+export interface ModelBinding extends BaseBinding {
+    kind: "model";
+    el: Element;
+    target: ModelTarget;
+    write: (state: any, props: any, shared: any, pending: (key: string) => boolean, value: any, ...locals: any[]) => void;
+}
+/** Re-evaluates a `$for` collection and hands it to the block to reconcile. */
+export interface ForBinding extends BaseBinding {
+    kind: "for";
+    block: ForBlock;
+}
+export type Binding = ElementBinding | PropBinding | ModelBinding | ForBinding;
+/**
+ * Where an expression is evaluated.
+ *
+ * Rows share their component's state and props but carry their own loop
+ * variables and their own cleanup, so removing a row detaches exactly its
+ * listeners and cell subscriptions.
+ */
+export declare class BindingScope {
+    instance: ComponentInstance;
+    locals: any[];
+    cleanup: BindingHolder;
+    constructor(instance: ComponentInstance, locals: any[], cleanup: BindingHolder);
+    get id(): string;
+    get state(): any;
+    get props(): any;
+}
+export declare function resolveModelTarget(el: Element): ModelTarget;
+/**
+ * Compiles and applies template bindings.
+ *
+ * Bindings are collected once at mount and stored on whatever owns their scope
+ * - a component instance, or a single `$for` row. An update touches only that
+ * owner's elements. Nothing here queries the document.
+ */
+export declare class BindingEvaluator {
+    private cells;
+    private onPropChanged;
+    private compiledCache;
+    private writerCache;
+    /**
+     * @param onPropChanged Queues the child whose prop changed. Routed through
+     * the runtime's scheduler so prop cascades batch per frame like any other
+     * update, instead of recursing.
+     */
+    constructor(cells: CellManager, onPropChanged?: (instance: ComponentInstance) => void);
+    /**
+     * Loop aliases become function parameters, so `{{ item.name }}` resolves
+     * without a scope object or `with`. The cache keys on the parameter list too
+     * - the same expression means different things inside different blocks.
+     */
+    /** Compiled by the build, merged as components and pages register. */
+    private expressions;
+    private writers;
+    registerExpressions(expressions?: Record<string, any>, writers?: Record<string, any>): void;
+    /**
+     * The function the build compiled for this expression.
+     *
+     * Not compiled here: `new Function` is what forces a page to allow
+     * `unsafe-eval`. The build emits a table keyed exactly as this cache was
+     * keyed, so a lookup replaces a compile. See [[ADR-016]].
+     */
+    private compile;
+    private compileWriter;
+    createBinding(el: Element, kind: "text" | "class" | "attr" | "show" | "html", expr: string, attr?: string, params?: string[]): ElementBinding;
+    createPropBinding(target: ComponentInstance, name: string, expr: string, params?: string[]): PropBinding;
+    /**
+     * `$cell:count="ui:clicks"` - hand a cell to a child as one of its props.
+     *
+     * Not a binding, deliberately. A binding is owned by whoever wrote the
+     * expression, and for a prop that is the *parent* - so the value only
+     * arrives while the parent is mounted and still evaluating. Here the
+     * subscription belongs to the child, which is the whole point: it survives
+     * the parent being flattened to HTML, never mounting, or mounting long
+     * after this one did.
+     *
+     * A pending cell writes nothing, so a declared default still stands. That is
+     * the ADR-005 distinction doing its job - "nobody has said yet" is not the
+     * same as "the answer is undefined".
+     */
+    bindCellProp(target: ComponentInstance, name: string, key: string): void;
+    createModelBinding(el: Element, expr: string, params?: string[]): ModelBinding;
+    createForBinding(block: ForBlock, expr: string, params?: string[]): ForBinding;
+    /** A plain read view of the cell namespace, with no dependency recording. */
+    readProxy(): any;
+    /**
+     * `pending('key')` in a template expression.
+     *
+     * Must record a read exactly like the cell proxy does. Without that a
+     * `$if="pending('x')"` would register no dependency, never re-evaluate when
+     * the cell fills, and leave a permanent placeholder with no error - which is
+     * why this shares `onRead` with the proxy rather than reaching for the cell
+     * directly.
+     */
+    pendingProbe(onRead?: (key: string) => void): (key: string) => boolean;
+    /** For `$needs`, which asks about cell readiness rather than values. */
+    get cellManager(): CellManager;
+    /** Compile a standalone expression, e.g. a `$key`. */
+    compileExpression(expr: string, params?: string[]): Compiled;
+    evaluate(expr: string, instance: ComponentInstance, locals?: any[]): any;
+    applyBinding(binding: Binding, scope: BindingScope): void;
+    /** Re-evaluate everything owned by this instance, including its blocks. */
+    updateInstance(instance: ComponentInstance): void;
+    updateRow(instance: ComponentInstance, row: Row): void;
+    private updateBlock;
+    /** Re-evaluate an instance and everything below it. */
+    updateTree(instance: ComponentInstance): void;
+    /** Listen for edits and push them back into state. */
+    attachModel(binding: ModelBinding, scope: BindingScope): void;
+    private readFromDom;
+    private apply;
+    private applyModel;
+    /**
+     * Keep a binding subscribed to precisely the cells it read.
+     *
+     * Re-derived on every evaluation so conditional reads stay correct - an
+     * expression like `shared.a ? shared.b : shared.c` touches different cells
+     * depending on the value of the first.
+     */
+    private syncCellSubscriptions;
+    /** What a string `$class` last added, so it can take it back. */
+    private appliedClasses;
+    private updateClasses;
+}
+/**
+ * `$show` - hide without destroying.
+ *
+ * The counterpart to `$if`, which rebuilds its subtree and takes any DOM state
+ * with it (ADR-007). A half-typed input, a scroll position or a focused field
+ * inside a toggled region survives this and does not survive `$if`.
+ *
+ * The element's own display value is remembered the first time it is hidden,
+ * so restoring never has to guess - clearing the property outright would
+ * discard an inline `display` the author set.
+ */
+/** Marks an element hidden by `$show`. Paired with HIDDEN_RULE in the CSS. */
+export declare const HIDDEN_ATTR = "data-lsp-hidden";
+export {};

package/dist/types/src/runtime/bindings/index.d.ts

@@ -0,0 +1,2 @@
+export { BindingEvaluator, BindingScope, resolveModelTarget } from "./BindingEvaluator.js";
+export type { Binding, BindingKind, ElementBinding, PropBinding, ModelBinding, ModelTarget, ForBinding, } from "./BindingEvaluator.js";

package/dist/types/src/runtime/compiler/ImportTransformer.d.ts

@@ -0,0 +1,11 @@
+interface ImportInfo {
+    variable: string;
+    path: string;
+    type: "default" | "named" | "star";
+}
+export declare class ImportTransformer {
+    transformImports(logic: string): string;
+    private pathToComponentId;
+    extractImports(logic: string): ImportInfo[];
+}
+export {};

package/dist/types/src/runtime/compiler/index.d.ts

@@ -0,0 +1 @@
+export { ImportTransformer } from "./ImportTransformer.js";

package/dist/types/src/runtime/components/ComponentInstance.d.ts

@@ -0,0 +1,110 @@
+import { SignalManager } from "../signals/index.js";
+import type { Binding } from "../bindings/index.js";
+import type { BindingHolder, ForBlock } from "../dom/ForBlock.js";
+export declare class ComponentInstance implements BindingHolder {
+    /** Unique per mount, e.g. "button#2". Keys the runtime's instance map. */
+    id: string;
+    /** The component definition this was mounted from, e.g. "button". */
+    componentId: string;
+    parent: ComponentInstance | null;
+    children: ComponentInstance[];
+    /** Top-level nodes this instance owns in the DOM. */
+    rootNodes: Node[];
+    /**
+     * Elements this component named with `$ref`, by name.
+     *
+     * Filled while the DOM is collected - which is *after* `setup` runs - so
+     * logic reads them in `onMounted` and not before. The object identity is
+     * stable, so a component can hold the reference it was handed at setup and
+     * find it populated later.
+     */
+    refs: Record<string, Element>;
+    /**
+     * `onMounted` callbacks, waiting for this instance's nodes to be in the
+     * document.
+     *
+     * Held rather than run, because logic runs *before* the DOM exists: `setup`
+     * happens first, then the template is built or adopted, then the nodes are
+     * inserted. A callback that measures something, focuses something or
+     * observes a node needs the last of those to have happened.
+     */
+    mountedCallbacks: Function[];
+    /**
+     * Cleanups registered by the component's logic - signal listeners, cell
+     * subscriptions, `onUnmounted`. See {@link addLogicCleanup}.
+     */
+    logicCleanup: Function[];
+    /** Bindings whose expressions evaluate against THIS instance's scope. */
+    bindings: Binding[];
+    /** `$for` blocks declared directly in this component's template. */
+    blocks: ForBlock[];
+    /** Style scope hash for the component this was mounted from. */
+    scopeId?: string;
+    props: any;
+    state: any;
+    handlers: Map<string, Function>;
+    /**
+     * `onUpdate` callbacks, run *before* this instance's bindings re-evaluate.
+     *
+     * Before rather than after, deliberately: a callback exists to recompute
+     * state a binding is about to read, so running it first means the same pass
+     * picks it up - and a write from inside it cannot schedule a second pass to
+     * do what this one was already going to do.
+     */
+    updateCallbacks: Function[];
+    /**
+     * Handler names an event expression is compiled with, fixed at build.
+     *
+     * Not `handlers.keys()`: that is whatever the instance registered, which the
+     * build cannot know for a handler created at runtime. See [[ADR-016]].
+     */
+    handlerNames: string[];
+    signals: SignalManager;
+    cleanup: Function[];
+    /**
+     * Evidence that this instance needs the browser.
+     *
+     * Recorded while it renders rather than inferred from its source: component
+     * logic is arbitrary JavaScript, and what it *did* is knowable where what it
+     * *might do* is not. A build that watched an instance mount and saw it
+     * register nothing has better grounds than any parser.
+     *
+     * Not a guarantee - a listener attached from a promise is invisible here -
+     * which is why this decides a warning today and not what ships.
+     */
+    listeners: number;
+    models: number;
+    /** `onMounted` was asked for. It never runs at build, but wanting it counts. */
+    wantsMount: boolean;
+    /** Cells it declared that are not fetched at build. */
+    runtimeCells: Set<string>;
+    constructor(id: string, componentId: string, signals: SignalManager, parent?: ComponentInstance | null);
+    addHandler(name: string, fn: Function): void;
+    getHandler(name: string): Function | undefined;
+    hasHandler(name: string): boolean;
+    addCleanup(cleanup: Function): void;
+    /**
+     * A cleanup that undoes something the component's *logic* set up.
+     *
+     * Kept apart from the DOM-owned ones because the two have opposite fates on
+     * a rebuild. When adoption bails, the rendered nodes are thrown away and
+     * everything attached to them has to go with them - but **the logic has
+     * already run and will not run again**, so anything it registered is the
+     * only copy there will ever be. Running these would silently unsubscribe a
+     * component from its own signals and leave it looking alive.
+     *
+     * Handlers were already protected from exactly this. Subscriptions were not.
+     */
+    addLogicCleanup(cleanup: Function): void;
+    /** Drop everything tied to the DOM being replaced, and only that. */
+    releaseDom(): void;
+    addBinding(binding: Binding): void;
+    addBlock(block: ForBlock): void;
+    /**
+     * Tear down this instance and everything below it.
+     *
+     * Children go first so their cleanup runs while their parent is still
+     * intact. Does not touch the DOM - the mounter owns node removal.
+     */
+    destroy(): void;
+}

package/dist/types/src/runtime/components/ComponentRegistry.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentDefinition } from "./types/index.js";
+export declare class ComponentRegistry {
+    private components;
+    register(component: ComponentDefinition): void;
+    update(id: string, component: ComponentDefinition): void;
+    get(id: string): ComponentDefinition | undefined;
+    has(id: string): boolean;
+    getAllIds(): string[];
+    getAll(): ComponentDefinition[];
+    clear(): void;
+}

package/dist/types/src/runtime/components/index.d.ts

@@ -0,0 +1,3 @@
+export { ComponentRegistry } from "./ComponentRegistry.js";
+export { ComponentInstance } from "./ComponentInstance.js";
+export type { ComponentDefinition } from "./types/index.js";