asHook
asHook specification
What asHook Is
Section titled “What asHook Is”asHook is a special prototype form in Proto UI. Like a prototype, it has setup and can declare props, state, event, feedback, expose, rule, lifecycle, and other capabilities. Unlike a prototype, it has no independent interaction subject and only exists while attached to another prototype during that caller setup.
Intuitively, an asHook means “be this kind of interaction subject” or “inherit this behavioral protocol.” When a prototype calls asFocusable(), it is not composing a new child component. It is making the current prototype inherit focusable identity and related capabilities.
asHook is not an information channel and not prototype-level composition. It does not create an independent component instance, runtime instance, or template root. All effects it introduces belong to the caller prototype.
asHook And use-style Hooks
Section titled “asHook And use-style Hooks”asHook is inheritance-like: the caller declares that it is a kind of interaction subject or inherits a behavioral protocol. It usually has no parameters, and it applies once by default.
Compositional logic reuse is closer to a useXxx hook. If a helper is only an ordinary function wrapper, prototype authors can write the function themselves. A governed hook API becomes useful only when it needs trace, capture, setup guards, artifacts, disposers, or conflict diagnostics.
The public Core package already exports defineHook, and existing Base helpers use it. The draft decision D-AS-HOOK-DEFINE-HOOK-0001 leaves its classification and stabilization alongside defineUseHook unresolved; that decision does not prohibit the implemented API or make it part of the core asHook contract. The current legacy implementation uses named installations and mode / configure; it must not be confused with the historical generic candidate’s typed raw value and definition identity.
Definition And Naming
Section titled “Definition And Naming”defineAsHook(spec) accepts at least the same baseline definition shape as definePrototype(spec):
import { defineAsHook } from '@proto.ui/core';
export const asPressed = defineAsHook({ name: 'as-pressed', setup(def) { const pressed = def.state.fromInteraction('pressed');
def.expose.state('pressed', pressed); },});The name field is the prototype spec name and follows prototype kebab-case naming rules. The exported caller binding should appear as asXxx, but runtime cannot reliably know which variable the returned caller was assigned to. Validating the asXxx caller binding therefore belongs to lint, CLI, generator, or TypeScript tooling.
asHook setup still follows the prototype setup contract: it may return only a render function or void. AsHookResult is not the direct setup return contract; it is the caller return value produced by the asHook runtime from captured setup effects, handles, artifacts, and an optional render return. An asHook render fragment does not commit automatically; the caller must compose it explicitly.
Invocation Period
Section titled “Invocation Period”An asHook caller can be invoked only during caller setup:
export const button = definePrototype({ name: 'button', setup(def) { asTrigger(); const focusable = asFocusable(); focusable.configure({ disabled: false }); const pressed = def.state.fromInteraction('pressed');
return () => ({ type: 'button', style: pressed.get() ? tw('translate-y-px') : undefined, children: 'Button', }); },});Render, lifecycle callbacks, event callbacks, props watchers, context watchers, and other runtime periods cannot add new asHook applications. Runtime behavior must be declared by the asHook during setup and later execute through existing callback, state, feedback, event, expose, or related contracts.
Default Repeat Policy
Section titled “Default Repeat Policy”The default asHook repeat policy is once. Within one caller prototype setup chain, the same asHook identity installs only once by default. Later calls with the same identity must be skipped and should not throw.
This prevents inheritance-like interaction identity from being installed repeatedly and producing duplicate side effects. Hooks that need parameter merging, latest-wins behavior, or multiple installations must define that through privileged asHook contracts or future explicit contracts. They are not default asHook semantics.
Effects And Ownership
Section titled “Effects And Ownership”Setup effects introduced by an asHook through def belong to the caller prototype:
asHook setup -> def.state / def.event / def.feedback / def.expose / def.rule / ... -> captured setup effects -> attached to caller prototype -> executed by each owning module contractThe asHook runtime only captures, attaches, and exposes results. Each module still owns its own dedupe, merge, conflict, diagnostic, and execution-order semantics. asHook does not create independent props/state/event/feedback/context/expose/rule runtime domains for itself.
An asHook may depend on any sub-API on the def handle. Using def.props, def.state, def.event, def.feedback, def.expose, def.context, def.rule, def.lifecycle, or another setup API is normal asHook design, not over-coupling. The same phase rules apply as in prototypes: def declarations happen during setup, and callback APIs declared by the asHook may later receive run in the same way prototype-authored callbacks do.
Current capture buckets are implementation details, not public semantics. Contracts describe which setup effects are captured, which artifacts/disposers/handles are exposed, and how those effects attach to the caller.
AsHookResult
Section titled “AsHookResult”AsHookResult is the return value of an asHook caller. It may expose:
| Result | Meaning |
|---|---|
| handles | Stable handles introduced by the asHook for caller consumption |
| artifacts | Analyzable products such as event keys, method descriptors, or style handles |
| render fragment | Renderable fragments that the caller must compose explicitly |
| disposers | Functions for undoing reversible setup effects during setup |
The disposer boundary matters: disposers let the caller undo setup effects introduced by the asHook during setup. They are not runtime cleanup, callback disposers, or lifecycle disposers.
Contributions that cannot or need not be removed may expose only handles or artifacts. For example, creating a state slot usually does not need “delete this state” semantics; not consuming it is enough to cancel its use.
State Projection
Section titled “State Projection”Controllable state created or introduced inside an asHook should be projected to the caller as a borrowed view, not an owned view.
The caller may read it, set defaults, set runtime values, and register watchers; however, the state source remains reusable logic introduced by the asHook rather than state directly declared and fully owned by the caller.
System-maintained facts introduced by privileged asHooks may instead be exposed as observed state-backed handles. They should still carry standard state metadata so rule, expose, and diagnostics can consume them as state-shaped values.
Interaction state follows the same boundary. If an asHook declares interaction state internally, that state must belong to the caller interaction subject rather than becoming asHook-private state.
The caller prototype must retain readonly trace metadata for applied asHooks. Trace supports diagnostics, anatomy requirement checks, tooling display, and implementation debugging.
Trace should include at least:
| Field | Purpose |
|---|---|
| identity | Identifies the applied asHook |
| order | Records application order |
| privileged | Marks whether the asHook is privileged |
| repeat policy | Exposes stable repeat-policy information |
Trace is not writable prototype-author state and is not a runtime behavior channel. Diagnostic systems may read it, but must not inject behavior through it.
Privileged asHooks
Section titled “Privileged asHooks”A privileged asHook is an official asHook form that exposes powerful, host-sensitive, or otherwise non-author-facing module-port capabilities to prototype authors through a restricted API.
Typical areas include focus, overlay, hit participation, interaction boundary, and APIs such as asTrigger that need to move event targets or coordinate multiple modules.
Privileged asHooks still share the normal asHook def syntax rights. They should express props, state, event, feedback, expose, context, rule, lifecycle, and other prototype-syntax behavior through def where possible. Non-public module ports, facades, or host capabilities should be reserved for the parts that ordinary prototype syntax cannot express.
Each privileged asHook is its own API and must define:
| Item | Meaning |
|---|---|
| parameters | Whether parameters are allowed, whether they affect identity, and how they are validated |
| return value | Which handles, artifacts, or restricted facades are exposed |
| repeat policy | Whether it remains once or uses custom merge rules |
| configuration merge | How repeated calls merge, override, or report conflicts |
| safety boundary | Which capabilities can be rolled back and which cannot for safety or host reasons |
Privileged asHooks must mark privileged: true in trace metadata.
Deferred Scope
Section titled “Deferred Scope”The following items are recorded as debt or governed design space, but are not stable v0 asHook core:
| Item | Status |
|---|---|
| caller binding name validation | spec.name and asXxx caller binding are separate; tooling should validate the binding later |
| ordinary configurable authored asHooks | Implementation support exists, but option identity, configuration merge, and conflict diagnostics remain governed |
defineHook / defineUseHook | defineHook is implemented; classification and stabilization of a separate use-style API remain unresolved |
| capture bucket shape | Current runtime buckets are implementation details and are not public semantics |
| privileged asHook details | Defined by secondary scopes such as focus, overlay, and boundary |
Contract Preview
Section titled “Contract Preview”Relationship To Tests
Section titled “Relationship To Tests”asHook test entities are organized around core behavior, result capture, and privileged capabilities:
| Test entity | Main coverage |
|---|---|
T-AS-HOOK-0001 | subjectless attachment, setup-only caller, prototype-compatible definition, default once policy, readonly trace |
T-AS-HOOK-0002 | caller-owned captured effects, AsHookResult artifacts, setup-only disposers, borrowed state projection |
T-AS-HOOK-PRIVILEGED-0001 | privileged module-port capability, privileged trace, rollback boundary |
Current runtime contract tests cover core asHook behavior. Focus, boundary, overlay, and hit-participation tests carry the minimum privileged API boundary.
Implementation Evidence And Limits
Section titled “Implementation Evidence And Limits”The retained 2026-10-11 generic-hook source record reports 35 passing original Runtime and Base helper cases on Node 22.23.3, plus separate type, capture-failure, and ordinary-projection checks. Those results belong to that historical source candidate. Its broader run also retained 105 general failures and 98 WC failures matching the frozen baseline; the focused result was never an all-suite pass. See the source accounting in the retained reconciliation record.
Issue #1154 keeps documentation synchronization and owned-script archival with projection verification as separate conditions. New current-source container evidence must bind its exact source, release tarballs, package exports, generated CLI facade, and isolated consumer. An ordinary asHook test or a working facade does not establish the retained generic candidate’s raw-value, typed-argument, identity, failure, or non-Web composition conditions.
The first bounded current-source run completed real package packing, installation, and CLI help/init/add. Its generated WC Collapsible consumer started open, closed on the pointer request, ignored a later default change, and reopened through the public method. The generic conditions remain unaccepted: the run retained identity, failure, metadata, and compiler-import refusals, alongside a numeric-factory typo in the newly authored probes and the archive’s missing Git metadata prerequisite.
The owned probes and Git archive preparation are being corrected for a narrow rerun using those unchanged packed packages. The documentation type/build attempts reached their original deadlines before token generation completed; their logs do not establish a TypeScript or Astro error. Corrected-probe, Git-dependent-check, and rendered-page acceptance remain pending. No draft contract or target profile is promoted by this evidence accounting.
2026-11-12 Disposition
Section titled “2026-11-12 Disposition”The subsequent bounded R2 run passed the corrected legacy defineHook consumer: setup ran once, repeated calls returned the same captured result, and its declared numeric state changed from 1 to 3 through the registered event. This result establishes that existing consumer behavior for the retained packages. It does not establish the historical candidate’s typed raw-value API.
The intended two-argument raw-value consumer still failed with [AsHook] setup() must return render function or void, got: object. Its packed TypeScript check also retained the incompatible AsHookConfigApi / numeric argument, the caller’s 0–1 argument limit, and the unknown value type. Current HookPrototype defines setup(def, options, api) => RenderFn | void; its caller accepts one optional options value and returns a synthesized HookResult. Changing the fixture to that legacy shape would remove the intended tuple and raw-value conditions. Those source and type assertions remain intact. A separately resolved generic API definition, its Core/Runtime realization, and source-neutral Compiler support are prerequisites for that capability. The equal-name identity, reentry/failure, and retired metadata assertions, including configure, also remain unmet historical-candidate conditions.
R2 copied and read back real Git metadata successfully. Its Agent operations check then emitted named connector failures before reaching the original 900000 ms deadline with SIGKILL; successful Git admission does not make that check pass. The earlier documentation type/build deadlines predate the separately reported token-generation repair and remain historical outcomes, with no post-repair rendered-page result established here. Both R1 Compiler profiles retained PUI1003: Unsupported import defineHook from @proto.ui/core.
Source review found that R1’s reported static-declaration pass was vacuous: both compared modules values were absent, and Object.isFrozen(undefined) is true. The repaired probe uses two real public Core declarations and requires their complete authored order, exact declaration/token/config references, required fields, and frozen array, token, declaration, and top-level config surfaces, following the draft C-MODULE-DECLARATION-0001 substrate. Publishing these declarations from defineHook is the retained historical K target; current legacy HookCaller has no public modules commitment. The expected new failure therefore identifies an unmet historical capability, with no new execution or current Core regression established. A new fixture-only container entry reuses the retained packages and runs only this changed probe. All 13 retained generic conditions and both original #1154 checkboxes remain unearned pending their actual validation and integration; this disposition does not promote any draft contract or target profile.
Actual Bounded R3 Result
Section titled “Actual Bounded R3 Result”Main subsequently executed the fixture-only R3 run against the retained installed packages. Its requested and executed probe lists were both exactly ['static-module-declarations'], with no unmatched selector. The probe failed at consumer line 324 with retained C-HOOK-0001-K target requires a Module declaration array. The container command exited 1 with no signal or timeout; the existing 1200-second container and 180000 ms probe deadlines were unchanged.
Five of the six execution phases passed, including source and real Git metadata admission, retained-input binding, and the final package/index readback. All 41 retained packages kept their tarball, export, installed-membership, and lockfile bindings; the semantic index matched before and after. The static probe stopped at the missing array, so its later order, exact declaration/token/config identity, required-field, and freezing assertions were not reached. This is an actual failure of the historical K target. Current legacy HookCaller has no public modules commitment, so this result does not establish a current Core regression. R1’s vacuous reported pass remains preserved as history and supplies no static-declaration acceptance.
R3 did not rerun R1/R2 or the other probes, type checks, Compiler profiles, or documentation builds. The authored raw-tuple and type fixtures retained their exact R2 bytes. Their historical generic definition remains absent from the current catalog; no new API semantics are introduced by this result. All 13 original generic conditions and both original #1154 checkboxes remain incomplete, with source review, applicable projection validation, and integration still owned separately by Main.
Git Metadata Custody Clarification
Section titled “Git Metadata Custody Clarification”Independent review CLI1154-ADMISSION-001 established that .env.production was omitted from the working-tree copy while its tracked bytes remained readable through the admitted Git objects and semantic index. That complete metadata is mounted at /source/git-metadata and copied into /work/repo/.git. The reviewer reported only the 24-byte size and matching hash; no values were disclosed and no secret leak was established. The exclusion therefore describes the working-tree copy, not absence of those bytes from the whole mounted snapshot. The harness now states that boundary and distinguishes newly configured Git settings from retained tracked contents.
This correction changes provenance wording only. It changes no consumer execution condition, Git-object/index custody, or admission/rejection policy. The original R3 receipts retain five passing phases and the historical K array failure; they were not rewritten or replayed. All 13 generic conditions and both original #1154 checkboxes remain incomplete.
Relationship To Other Specifications
Section titled “Relationship To Other Specifications”Coredefines prototype setup, render returns, and setup/runtime phase boundaries; asHook reuses those foundations.Statedefines owned, borrowed, and observed views; state exposed by asHook projects to borrowed views.Event,Feedback,Expose,Context,Rule, and other modules own their effects’ dedupe, merge, conflicts, and execution order; asHook only attaches those effects to the caller.Anatomymay read asHook trace to check role requirements, but cannot inject behavior through trace.- Privileged asHooks may use module ports unavailable to ordinary prototype-author APIs; those capabilities require their own secondary contracts.