Imported from AndrewRedican/hyperfrontend (.claude/skills/koi-pond-demo/SKILL.md). Install upstream with npx skills add AndrewRedican/hyperfrontend --skill koi-pond-demo. Copyright stays with the author.

Koi Pond Demo

Eleven Nx projects in apps/demos/koi-pond/. A host pond opens one fish feature app per koi (eight framework apps to draw from), each rendering one 3D koi into its own transparent iframe; the host composites them into one scene, owns the pointer, and relays neighbours. The pond is itself a hostee the docs-site gallery mounts. A shared lib (packed to a tarball) carries the model, contracts, the steering brain, the frame loop, geometry, the renderer-free 3D koi, and the three.js adapter. A workbench develops the koi model in isolation.

Projects → dirs (Nx name = commit scope)

The thesis (what any change must not break)

The lib owns the whole simulation: body, physics, steering brain, the frame loop, the wire plumbing, the three.js stage, fish.css. Each fish app owns only its framework's mounting, rendering, and lifecycle idiom (src/state/koi.ts composing createKoiRuntime, plus one renderer/component module). The brain is configurable, not copied: KoiMotionOptions.onDecision watches what it commits to and desire biases the ladder; createKoiRuntime takes a motionFactory and a rendererFactory. Never re-fork per-fish brains, and never let a fish app grow simulation logic.

How it connects

• Two contracts. Inner lib/src/contract/koi-fish.contract.ts v0.8.0 (pond host ↔ each koi): host sends pond/identity/neighbors/disturbance/depth/hover/sleep/pause (press-to-hold; pause {paused, resting} holds position, keeps the scull and suppresses ALL held chrome) /place (drag a held koi to a pond point); koi emits outline/depth-request/ripple-request/settled. identity carries a required instance ordinal (0 = canonical fish, 1..n = duplicates) and the host-dealt seed; outline optionally carries path (up to 20 points of predicted advancement, capped by the producer). outline+neighbors are schema-less (hot path); the outline ordinarily carries intent: KoiIntent {kind travel|avoid|depth-change, heading, gain, target, direction?, reachPx, clearancePx}, suppressed while held; while HELD it instead carries card: KoiCardPanel {frame, app, site, source} and the host floats three real <a target=_blank> anchors (.koi-card-link) plus an inert .koi-card-shield (all stopPropagation on pointerdown; fish frames are pointer-transparent so fish-side links can never be clicked). Outer host/koi-pond.contract.ts v0.2.0 (gallery ↔ pond): gallery sends set-scene (card/full) /disturb; pond emits shoal/sequence-complete/close-request {source: button|escape}. Escape inside the pond releases a held koi first, else emits close-request (escape-close.ts + featureUi.requestClose(source), latch re-armed by set-scene) — the host page can never hear keydown once focus is in the pond's document. The pond re-emits shoal every 10s as a liveness roll call; the docs-site embed declares a demo offline after 30 quiet seconds. The gallery is never told how many apps are behind the scene.
• The scene is decided once, before anything opens. wireSceneBoot(feature, scene, { hosted: feature.hosted }) (host/src/feature/wire-contract.ts): unhosted opens full in the same tick; hosted holds the water empty until the first set-scene, a non-embedded presentation (dialog/popup/host-opened tab reads as full immediately), or SCENE_FALLBACK_MS (1s). An instance never morphs: a contradicting set-scene later is diagnosed scene:ignored and changes nothing. hosted is the SDK handle's synchronous flag (features ≥0.8.0); the pond uses no URL params and no window.parent. Never describe hosted: false as "standalone" — every DisplayMode is hosted; say "top-level" or "a direct visit".
• Two profiles. openProfile in pond.ts: card = one koi, KOI_FRAMEWORKS[bootHour % 8] ordinal 0, world from describePondForFrame(root.clientWidth, root.clientHeight) (the card's own frame, not the screen through a keyhole), held resting from open and placed at the pond centre, all chrome hidden by #pond[data-scene='card']. full = the hour-anchored koi and the frameworks after it in list order (all ordinal 0), screen-derived world, growable by hand; how many is openingShoal(root.clientWidth, root.clientHeight, device.cap) in runtime/device-tier.ts — bands on the frame's geometric mean sqrt(w*h): ≥1000px → 8, ≥640 → 5, ≥320 → 3, else 1, with an unmeasured frame standing in 800×600. Card is always 1 whatever it measures. Both clamp to device.cap. The centre place is not decoration: entryStation lays out the whole canonical shoal and relaxes it for separation, so on card-sized water every station is pushed to the reach cap and the lone koi hangs half outside the frame.
• Every session is an instance. KoiInstanceId is the branded string framework:ordinal (host/src/scene/instance-id.ts: koiInstanceId, instanceFramework, instanceOrdinal, nextOrdinal); the wire never sees it, the host converts at the channel boundary. Layers carry data-fish (framework) and data-instance (id). Relay self-exclusion, depth slots, retries, resurrection budgets, sequence tracking and held chrome are all per instance — that is what makes twins avoid each other. koiVariantSeed(framework, ordinal) deals a duplicate its own body; the runtime's adopt() rebuilds profile, brain and renderer around a dealt seed that differs from its canonical assumption.
• The dynamic shoal. PondSceneHandle: addKoi(framework) → new id or null at the cap (onDiagnostic(null,'shoal:refused','<tier>-tier device seats <cap>')); removeKoi(id) → false for unknown or the last fish ('the pond is never empty'), closes politely then tears the layer down on close or after a 4s grace, ordinal stays spoken for until the layer is gone, pending revives/retries die with it; shoalState() → {tier, cap, roster}. Device profile read once at construction (runtime/device-tier.ts, navigator.deviceMemory+hardwareConcurrency, no UA sniffing): low ≤2GB or ≤2 cores → cap 4; high ≥8GB and ≥8 cores → cap 12; middle (and anything withholding a signal, so Safari/Firefox) → cap 8. The low gate is narrow ON PURPOSE (it was ≤4 cores and put ordinary four-core laptops on a 4-koi shoal): what a device holds at once is the opening band, the cap only bounds hand-stocking. Eight frameworks, so duplicates are only reachable above 8 — the cap is the only duplicate gate.
• The shoal panel (host/src/scene/roster.ts createShoalPanel, nav.koi-shoal z-index 165) is the control surface and contains its own pointer/click events. Every framework keeps a row (presence dot, name linked to that app, count badge hidden at zero, add control, nested per-koi remove controls). Focus is the keyboard's hover: a framework name/add lights all its answering koi, a remove control lights one. A control stranded by a rewrite hands focus onward (row add → newest koi's control → row name). The cap is stated: at the ceiling every add disables and names the tier, else the note counts the room left. "View interactions" and the "Source on GitHub" link live in the panel. Under PILL_BELOW_PX (680) it collapses to a pill rather than hiding, so a phone in the full scene keeps every gesture.
• World vs view. PondEnvironment.width/height is the virtual pond (from window.screen, clamped 800×600..3840×2400, or from the card's frame); pond.view {x,y,width,height} is the visible window, recomputed on every resize. Simulation/spawn/steering read the world; camera/canvas/culling/pointer read the view. Resize must NEVER rebuild the world. A fish app always builds a screen-derived world at construction so it can swim unhosted, so runtime.setPond re-stations the koi whenever the announced world's dimensions differ from the one it guessed (entryStation in the world it was actually given, brain rebuilt). Without that a card koi keeps a screen-world station, sits far off card-sized water, and its renderer culls it forever: empty water behind an open curtain.
• Mounting = embedded. Host makes one position:absolute;inset:0 layer per koi. z-index is the depth model (depthZIndex, seven levels): floor 0, fish z1..7, water z100, #interactions z120, card shield z158 / links z160, shoal panel z165, curtain z200, dialog close z210, vitals z220. Owning the layers is also what lets the host stand one down: present (a Set in pond.ts, driven by open/close/error/watchdog status) is the single source for setLayerPresent, the panel and the shoal count, because a frame the browser has killed keeps painting an opaque crash placeholder. scene/resurrection.ts re-opens a session whose error: unresponsive verdict outlives a 4s grace (backoff 4/12/36s, 3 attempts per episode, budget restored after 60s present; deferred while hidden; forget(id) when the roster drops a koi).
• Interaction overlay. The panel's "View interactions" flips scene.setInteractions(on); the frame loop feeds relay.latest outlines to scene/interactions.ts. One ink (OVERLAY_INK, white) at varying alpha — no code path produces a colour. Field (paintField): the koi's REAL encounter window, not an approximation — a band intent.clearancePx either side of the heading running intent.reachPx ahead, which is exactly the pair resolveEncounter gates a crossing on (CPA within ENCOUNTER_HORIZON_S 2.4s and inside max(len)*0.55 + both girths). Hung from the reported NOSE (the point the narrow phase judges from) and opened FIELD_STANDOFF_BODIES 0.12 body ahead of it, so it can never paint over the koi at any build — the whole body lies behind that point. Drawn as ONE fill: save/translate(nose+heading*mid)/rotate(heading)/scale(halfReach, clearance) then a unit-circle arc under a radial gradient focused at -FIELD_SOURCE 0.74 (FIELD_ALPHA 0.26 → FIELD_SHOULDER 0.55 at FIELD_SHOULDER_SHARE 0.34 → 0 at the rim). The ellipse's axes ARE the reported reach and clearance; only the corridor's corners are given up, where the ink had already run out. Never go back to stacked shapes for the falloff (9 shells banded visibly and cost 9 fills); canvas 2D has no 2D gradient, so the koi's own frame is what makes one smooth in both directions. It cannot express the depth gate, and the sim has no view angle at all — the region is a swept corridor, not a cone. Pearls (scene/pearl-trace.ts): drawn from the outline's own path (the host predicts nothing), spacing PEARL_SPACING_BODIES 0.1, PEARL_MAX 10 alight, 5–6px, alpha 0.8 at the nose → 0.1 at the horizon; a pearl never moves once placed — advanceTrace consumes what the nose passed, cuts from the first pearl >PEARL_TOLERANCE_PX (4px) off the fresh path, mints from the last survivor. Caret (scene/sliding-caret.ts): a drawn nested double chevron (outer + a 0.5-scale inner set back inside its arms), sized from the reporting body (CARET_ARM_BODIES 0.028, clamped 3.2–8.5px) and orbiting headCentre at beamOf(girth) + 0.12 body + CARET_ORBIT_BODIES 0.08 body (~0.30–0.33 body, phenotype-derived), sliding CARET_SLIDE_RAD_S 2 rad/s toward intent.heading, which outruns any helm the brain has. Weight = commitment(intent.gain) (0.12 drift → alpha 0.3, ≥0.55 committed → 0.9); the inner chevron FILLS when intent.kind !== 'travel', which is the avoidance cue. A held koi reports no intent and draws nothing. The painter keeps one chain and one caret per instance and drops both when that koi leaves.
• Pointer. Every layer + iframe is pointer-events:none; host runs one normalized stream, hit-tests against fish-reported outlines, notifies the winner. HOVER ≠ SELECTION: hover only says selectable (SOFT silhouette setOutline(0.35), cursor pointer/grab — no card); press = hold (pause; FULL silhouette setOutline(1) + card until release; picking a DIFFERENT koi releases the held one first); drag past slop (6px/12px touch) = carry (place streamed once per painted frame, grab-offset preserved, card chrome hidden while carrying); drop = release + resume; tap a held fish = release in place. The silhouette is renderer-native (inverted-hull koi-outline-skin/koi-outline-fins in lib/src/three/koi.ts sharing the live spine uniforms) — NEVER reintroduce a host-drawn rectangle. Mobile: touch-action: manipulation on #pond; a non-passive touchmove listener preventDefaults ONLY while a fish press is active.
• Rendering. Each fish owns its own transparent WebGLRenderer but renders ONLY its own frame box: koiFrameBox (lib) → square canvas ~1.7 body lengths, slid by CSS transform, camera narrowed via PondView.frame() (setViewOffset), buffer sized by fitPondRenderer (DPR≤2, 1280px cap), hidden + skipped entirely when outside the view. NEVER go back to viewport-sized fish canvases, and for the same reason createPondRenderer asks for antialias only below DPR 2. Release GL on hidden: sleep {paused:true} disposes the renderer after the loop stops; wake rebuilds it, staggered WAKE_STAGGER_MS 60 per ordinal so a returning shoal never creates every context in one frame — so every renderer factory must be re-invokable and its dispose must clear everything it mounted. The koi is anchored by PondView.placeKoi (nose → pond point), never by place. Host paints the bed canvas-2D (resize-only) and the moving surface on ONE WebGL context (water-gl.ts, caustics + crests + veil + card edge fade, ~0.72× resolution) with the 2D painter (surface-canvas.ts) as automatic fallback; every 2D surface caps at MAX_CANVAS_DPR 2 (scene/pixel-ratio.ts). The water context WILL be reclaimed from a backgrounded tab (measured: lost on return, and it is the shoal's own wake rebuilding 8 contexts that costs it). Recovery is three parts and needs all three: webglcontextlost → preventDefault() (a browser restores nothing you did not ask for) + rebuild on webglcontextrestored (buildScene, everything belonged to the dead context, and reset sizedTo); onLost tells the pond, which waits WATER_RESTORE_GRACE_MS 1500 and then calls reseatSurface(stage) — the canvas ELEMENT must go, since getContext on a lost-and-unrestored canvas returns the same dead context. Never check lost() only at the visible transition: the loss lands seconds later. A fish that loses its context outside a sleep/wake has the same hole (verified: stays LOST); its wake rebuild is what covers the ordinary case. All fish build the same camera from POND_VIEW (tilt 10°/fov 26°/exposure 1.15) via createPondView.
• Behaviour (all in lib/src/motion/ + lib/src/geometry/). Scheduled, not noisy: createPaceSchedule (loaf/brisk/burst, exclusive), createItinerary (seeded waypoints, ~10% forced through the visible view), slipsAway/wrapAcross/SHORE_ABSENT_S (one boundary approach in five slips out, 5s absence, toroidal re-entry), createEncounterMemory (latches the manoeuvre KIND ≥0.9s + turn tail-off — the anti-oscillation core). Brains keep their own clock (advance(dt)), decide at 10Hz, anchor evasions as absolute headings, and bound ordinary turns with seeded cooldowns. Costed manoeuvres: chooseTurnTier picks the least effort predicted to clear (evasionTiers subtle π/10 gain 0.55, normal π/5 gain 1, hard π/3 gain 1.6) permitted by tierWindowS (hard <0.8s, normal <1.6s to closest approach); the chosen break is anchored ONCE as an absolute heading and held until the ladder asks for a strictly heavier tier (EVASION_EFFORT), so the koi actually arrives on it — never re-anchor it off the live heading each beat, which turns the arc into an unbounded spiral the caret can never converge on, and fire onDecision on each fresh anchor; flankCrowding picks the side from the water, and at |crowding| ≤ sideEvidence (0.02) a seeded draw breaks right with rightBias 0.7 so head-on pairs mutually avoid; turnBrake 0.35 charges the commanded manoeuvre against cruise (never double-charged with turnSpeedTax). Turn dynamics: the heading's rate is a wound turnVelocity under TURN_ACCEL 2.2 rad/s² (never a step), ceilings from turnRate {0.35,0.8}×gain taxed by speed over cruise, TURN_APPROACH ramps every turn out; speed capped at MAX_SPEED_BL_S 3.4 with ACCEL_LIMIT_BL_S2 2.6. 3D side: turnBend saturates at 1.4 rad centred 0.4 (torso, NOT the 0.32 shoulder that read as a broken neck), bodyFlexibility keeps the skull near-rigid, the amplitude surge term is clamped (also why every renderer refreshes lastSpeed in its offscreen-skip branch).
• A koi opened on its own. lib/src/solo/ (solo-page.ts + framework-mark.ts): createKoiRuntime mounts it ONLY when the app passes hosted: false explicitly (silence reads as hosted — painted water inside a frame blanks every koi below it), and setPond/dispose take it straight back down. It prepends a .koi-solo-sky to body (DOM order, no z-index, so the koi's own canvas paints over it), appends a .koi-solo panel, and injects its own <style> (lit ships a different fish.css, so the sheet cannot be relied on). Contents come from what the lib already knows: profile.label, palette.pattern, palette.accent tinting a per-framework simplified mark, a FRAMEWORK_NOTES sentence on how that framework mounts THIS app, KOI_CONTRACT_VERSION, and links to FRAMEWORK_SITES / koiSourceUrl / the pond one path segment up (omitted when the app is its own origin root). Top-level ALSO changes the world: describePondForFrame(innerWidth, innerHeight) instead of the screen snapshot, so the fish stays in the window a visitor actually has open.
• Angular's host element. createComponent(KoiFish, {hostElement}) — Angular REMOVES that element on ApplicationRef.destroy(). Never hand it the app root: the runtime disposes and rebuilds the renderer on every wake and on every adopt with a dealt seed, so #app left after the first dispose, every rebuild mounted into a detached node, and the koi went invisible-but-still-reported (a hoverable ghost) — one backgrounded tab killed it, and every duplicate was born dead. fish-angular/src/koi/koi-render.ts gives it a display: contents div it makes itself.
• Predicted path. motion.predictPath(steps, dtStep) integrates with stepFlight, the same integrator the brain's own advance uses, so absent a new decision the realized trajectory passes within tolerance of every predicted point (mutation-proven parity spec). It deliberately ignores future decisions; when the brain commits mid-horizon the next emitted path simply disagrees from the divergence point and the overlay cuts the stale suffix. No extra signal is emitted.
• Vitals. ?vitals=1 (remembered per origin until ?vitals=0) mounts components/vitals.ts (z220): one probe row per living koi keyed and labelled by instance (rows follow .koi-layer[data-instance], arriving and leaving with churn), a boot record cores=… memory=…GB|unreported tier=… cap=…, and session/roster/visibility log lines through the PondHooks.onDiagnostic seam, probing every fish frame at 5s (same-origin classification incl. shadow-root canvases, buffer sizes, heap, webglcontextlost), debounce-persisted to localStorage so it survives a page death. added/removed name the instance and the roster size (4 of 4 koi); shoal:refused names the tier. The panel title reads vitals · visible|hidden from the visibility watch. While armed the scene handle also sits on window.koiPond. The card scene hides .pond-vitals (a card carries no chrome); the card instance still records, and the persisted log is restored by whatever instance comes next.
• Visibility. createVisibilityWatch (scene/visibility.ts) settles state from an event, a 2s poll, and a probe frame armed only while hidden; silence never puts the pond to sleep. It stops the loop, sleeps every session, and calls resurrection.pageVisible() on return. dispose() releases listener, poll and probe frame.
• Protocol. Inner channels run as explicitly open shells (protocol: 'none' in each fish feature.config, packed with --allow-open) — v1's per-message PBKDF2 is the F-011 collapse; transport stays origin-pinned. Outer gallery↔pond channel keeps protocol: 'v1'.
• Embedding. Each service ships public/hf-serve.config.json carrying frame-ancestors header rules for hf serve. frame-ancestors is checked against EVERY ancestor, so the koi value must name the pond AND the docs site (chain is docs-site → pond → koi); naming only the pond blanks the shoal. In the pond's file the koi override is a later "prefix": "/fish-" rule (later wins per header). All nine configs also send COOP same-origin + COEP require-corp + CORP cross-origin, so the standalone pond origin is crossOriginIsolated (the card's memory line measures there; embedded under the non-isolated docs-site it honestly stays unavailable). hf dev applies no header rules; to see isolation locally, hf serve --root the built site.

Commands (from repo root)

# lib: build + pack + reinstall into ALL consumers (ALWAYS run after editing lib/src)
npx nx run demo-koi-lib:refresh
npx nx run demo-koi-lib:verify          # fail loudly when tarball/consumer lock drifted
npx nx run demo-koi-lib:build           # tsc only; refresh does build+pack+install

# fish shells: repack all eight + reinstall into host (after inner-contract or fish feature.config changes)
npx nx run demo-koi-pond:refresh-fish-shells

# the whole family
npx nx run-many -t test build lint typecheck -p demo-koi-lib demo-koi-pond demo-koi-fish-*
npx nx run-many -t build -p demo-koi-*  # composed site → dist/apps/demos/koi-pond/site

# per project (only demo-koi-lib and demo-koi-pond carry a `test` target)
npx nx test demo-koi-lib
npx nx test demo-koi-pond
npx nx run demo-koi-fish-vanilla:build

Editing lib/src without :refresh ships stale code. A bare npm install no-ops on a same-version repack (warm cache reports "up to date"); refresh installs by explicit path, the only invocation that re-reads the tarball. After :refresh, run npm install inside a fish only if adding a new dep.

Run & debug

# composed pond on one origin (host + fish sub-paths), SDK dev server
npx nx run demo-koi-pond:dev-hosted     # app :4282, debug UI :4290
npx nx run demo-koi-pond:dev            # vite, host alone (fish frames 404 — use dev-hosted)

# serve the BUILT composed site (plain static server — NEVER serve -s)
npx nx run-many -t build -p demo-koi-*
npx http-server dist/apps/demos/koi-pond/site -p 4288

Never serve -s / any SPA rewrite — each missing /fish-*/ becomes a nested copy of the pond host.

Browser-verify the 3D shoal (headless, software WebGL — the docs-site has no dev script, so the composed site is the only live check):

// node script; full chromium (SwiftShader), not the headless_shell
import pkg from '/home/vscode/.npm/_npx/06476e4372e0b5ee/node_modules/playwright-core/index.js'
const { chromium } = pkg
const browser = await chromium.launch({
  executablePath: '/home/vscode/.cache/ms-playwright/chromium-1228/chrome-linux64/chrome',
  args: ['--no-sandbox', '--enable-unsafe-swiftshader', '--use-gl=angle', '--use-angle=swiftshader', '--ignore-gpu-blocklist'],
})
// goto http://localhost:4288/ — a direct visit is unhosted, so the frame's whole shoal opens at once;
// mouse.click(640,400) → ripple + scatter; sweep until [data-hovered="true"] → identity card;
// drive the shoal from the console via window.koiPond (needs ?vitals=1).

Panel rows carry data-connected/data-hovered; .koi-layer[data-instance] z-indexes prove the depth spread; curtain is [data-open].

Build & deploy

• Composed site: host builds to dist/apps/demos/koi-pond/site/ (emptyOutDir:false, base /); each fish to .../site/fish-<fw>/ (emptyOutDir:true, base /fish-<fw>/). Dev origin (dev-hosted) matches prod exactly.
• Deploy: one Railway service, GitHub-integration auto-deploy on merge to main (dashboard-owned — never propose in-repo deploy CI). host/project.json metadata.deploy: service hyperfrontend-demo-koi-pond, origin https://demo-koi-pond-production.up.railway.app, publishDir: dist/apps/demos/koi-pond/site. Build root must be at/above apps/demos/koi-pond so ../vendor is in context; host must not SPA-rewrite. Origin also in host/feature.config.ts url and docs-site demo-manifest.ts fallback — all three move together.
• Gallery shell (only needed if the outer contract or feature.config.ts changes — not for host scene edits):

npx nx run demo-koi-pond:pack-shell     # hf build → dist/apps/demos/koi-pond/shell/*.tgz
npx nx run docs-site:refresh-shell      # packs all demo shells + copies to docs-site/vendor + explicit-path install

Vendored shell + touched package.json + package-lock.json land together (a tarball without its locks fails npm ci EINTEGRITY on a cold cache). The koi shell name must stay in docs-site eslint.config.cjs ignoredDependencies or lint --fix deletes the dep.

Contract bump pipeline (the order that works)

1. demo-koi-lib:refresh then :verify (shells bake the contract from the installed tarball).
2. Bump every fish feature.config.ts version to match the contract.
3. demo-koi-pond:refresh-fish-shells — packs all eight and copies to host/vendor/, but never prunes.
4. Hand-delete the stale-version .tgz from both host/vendor/ and dist/apps/demos/koi-pond/fish-shell/*/.
5. Re-run node host/scripts/install-vendored-shells.mjs (the explicit-path install is the only invocation that re-reads a same-name tarball).
6. Commit tarballs, package.json and the lockfile together. All builds serial; never overlap two builds of one project (that is what produced the "nested vendor corruption" that turned out to be a race).

Key files

Cadence/budget constants: intentHorizonS=2 (the seconds a koi answers for its own heading over, which bounds intent.heading to the arc its helm can actually carry it through), OUTLINE_INTERVAL_MS=100 + MAX_FRAME_S=0.1 + WAKE_STAGGER_MS=60 (lib runtime), RELAY_INTERVAL_MS=120, RELAY_REACH=3.4, HOVER_SLACK=0.14 (TOUCH_SLACK_SCALE=2.6), DEAD_RECKON_MAX_S=0.6, STALE_REPORT_S=3, SHOAL_PULSE_MS=10_000, OPEN_TIMEOUT_MS=20_000, OPEN_RETRIES=2 + OPEN_RETRY_DELAY_MS=4000, CURTAIN_DEADLINE_MS=5000, SEQUENCE_DEADLINE_MS=14_000, SCENE_FALLBACK_MS=1000.

Edit a fish (mirror fish-vanilla)

A fish app is four files: hyperfrontend.feature.ts (the SDK handle), state/koi.ts (composes createKoiRuntime), koi/koi-render* (the renderer, injectable so lib specs run headless), and main.ts. Renderer contract: createKoiRenderer(root, profile, url, pond, createGl?) returns { koi, draw(state,dt), setPond, setHovered, placeCard, dispose }; it must be rebuildable from scratch on every wake and dispose must clear everything it mounted. Scene = koi group (koi-shadow/koi-skin/koi-fins/koi-eyes) + createLighting(POND_VIEW.lighting) via createKoiStage. Each fish declares three ^0.185.1 + @types/three ^0.185.4 (the lib peer is optional).

Adding a whole framework (angular precedent): KoiFramework union + KOI_FRAMEWORKS are append-only — list position is the koi's seed, reordering re-rolls every fish. Touch: palette (LABELS/BRAND/VARIETIES), HEFT, FRAMEWORK_SITES, tools/refresh-lib.mjs CONSUMERS, host koi-sessions.ts (shell import + factory map), host project.json refresh-fish-shells (dependsOn + cp line), count prose everywhere, docs-site copy. Trait/body draw offsets are append-only too (body band next free slot: 14 — 13 took caudalSpread; avoidance-side draws sit at band 640).

Angular specifics (fish-angular): AOT via @analogjs/vite-plugin-angular pointed at tsconfig.angular.json (extends the app config with noEmit: false — the default no-emit config makes every module compile to NOTHING with no error). Never set resolve.mainFields. Zoneless, no TestBed, no zone.js. Seam: createApplication → createComponent(KoiFish, { hostElement: root }) → setInput → attachView → tick(); dispose() must root.replaceChildren() after app.destroy(). Lint: @angular-eslint/eslint-plugin alone.

Gallery presentation

The docs-site card is a card-profile pond instance; expanding swaps instances. demo-manifest.ts marks the koi entry reopensOnExpand: true; use-expanded-embed.tsx holds a StagedSession {scene, generation} (expand-choreography.ts), and the surfaces mount <DemoEmbed key={sessionKey}>, so a scene change destroys the running session and opens a fresh one into the new container — never two live pond sessions. A session is told its scene on the shell's open event (the last moment the pond can still decide what to build); demos that carry one session across the scenes are told each change directly instead. CoverFlowCard restyles into fixed inset-0 (the deck drops its perspective while expanded — perspective is a fixed-position containing block) with shared ExpandedChrome ✕/Escape/next-demo controls (the ← → pair is hidden sm:flex); the neighbour buttons hand the stage over without opening a replacement. DemosGallery switches the host console to its overlaid widget while expanded. The landing DemoShowcase expands the same way (its frame container drops backdrop-blur-sm and its z-10 while expanded — a z-index makes it a stacking context, which trapped the overlay under the site header). Both surfaces subscribe shell.on('close-request', collapse). The deck caption restyles into a dark plaque under the translucent scene. The generic console "Open as dialog" opens a second session — dev tool only, never the product expand path.

Fish sizing: FISH_LENGTH_RATIO 0.36 of the world's shorter axis (clamp 130..560), margin 1.05 fishLengths; describePondForFrame bypasses MIN_POND so a 288px card yields a 288-scale world, with MIN_FISH_LENGTH 130 the governing floor. The caudal blade carries a lateral dihedral (caudal.spread, default 0.2, trait band 0.20–0.28) so the fork reads from straight above — a flat vertical blade vanishes edge-on on narrow portrait viewports (the S24-Ultra stub-tail bug); never zero it, and the band has to clear the bank (bank = turn*0.28, up to 0.36 rad). The blade also refuses the body's curvature: finFlexibility in spine-pose.ts fades curvature to CAUDAL_FLEX past CAUDAL_ROOT, and BLADE_DRIVE in swim-state.ts pays the lost tip reach back into the body wave (pose.spec.ts guards it). Phenotypes: koiPhenotype/koiTrim/heft in lib/src/model/traits.ts; varieties in palette.ts. The held card is a live inspector rendered by the FISH from shared describeKoiCard strings; memory uses performance.measureUserAgentSpecificMemory filtered to the fish's own attribution and honestly shows unavailable without cross-origin isolation; samplers run ONLY while held (card rows 500ms, memory 10s) and tear down on release.

Decision log

• 2026-08-23 — expand swaps instances (supersedes the 2026-08-09 "expand keeps one session, the card is a window onto the same scene" decision). A card-sized pond and a full-viewport pond are different worlds, not different windows onto one; stretching the card world over a viewport shows a scene nothing would have built there. Expand destroys the card session and cold-opens a full session behind its own curtain; collapse does the reverse, and the recreated card re-picks its hourly fish. Scoped by the manifest flag: clock and heartbeat keep single-session expand, because destroying a heartbeat session would throw away the rhythm it measured.
• 2026-08-23 — the lib owns the simulation (supersedes "the lib is a vocabulary, never a simulation engine; each fish composes its own brain"). Eight hand-maintained brains drifted and cost far more than they proved; the proof visitors can actually see is the framework seam, so the brain moved into the lib behind configuration hooks and the fish apps kept only their idiom.
• Card carries no chrome. No panel, no vitals, no toggle: the card is an invitation to expand. Diagnostics still record and persist.
• Duplicates are gated by the tier cap alone. No separate duplicate switch exists, and none should be added.

Gotchas

• Framing: a koi is mounted ONLY from its directory URL fish-<fw>/ — its assets are relative, so a host that rewrites …/index.html to an extensionless path drops the document a directory up and every asset 404s (this blanked the shoal in production once). Needs features ≥0.6.0 for directory URLs; the hosted flag needs ≥0.8.0.
• F-011: v1 message collapse across concurrent channels (root-caused; inner channels drop v1) — still open in roadmap/showcase/findings/. F-010/F-015/F-016 shipped in features 0.7.1; F-018/F-019 (gallery-side revival) and F-020/F-021 (hosted, visibility latch) are answered in the docs-site embed and features 0.8.0. The koi host pins the debug UI with debug.port: 4290 in hf-dev.config.ts.
• Per-fish three.js (~180 kB gzip each): inherent to independent apps; a shared chunk breaks the isolation the demo proves. Curtain covers the load. Not a bug.
• Unit tests live in demo-koi-lib and demo-koi-pond only. The eight fish-* apps carry no vitest, no test target, and no test devDeps by design. Do not add unit tests back to a fish app. Keep the lib's specs mutation-proven (disable avoidance → boundary specs fail) across all seeds, and never write ?.foo()).not.toBe(null) (passes on absent nodes). Canvas grammar is asserted through scene/__tests__/overlay-recorder.ts, a recording 2D context.
• Devcontainer: ten npm installs at parallel:1; full nx lint docs-site can SIGKILL — lint targeted file lists (npx eslint <files>).

Checklist

• Edited lib/src? → demo-koi-lib:refresh then :verify
• Changed the inner contract or a fish feature.config.ts? → the bump pipeline above, tarballs + package.json + lock together
• Scope = Nx project name; one project per commit; no version/changelog/tag files
• Comments never cite finding IDs / roadmap docs; shipped prose is present-state and em-dash-free in READMEs and JSDoc
• npx nx run-many -t test build lint typecheck -p demo-koi-* green
• Serving built site by hand → http-server, never serve -s