Design Log Index
Jay Design Log Index
Written for AI agents. See Log Methodology Note below for details.
Quick reference to find relevant design logs by topic. Design logs capture design decisions as they happen. A log's original design sections are never rewritten once implementation starts — a log is append-only from there: Implementation Results, findings, bugs, and deviations are added as new sections.
Each entry's description leads with a status tag: [Design] (approved/in-design, not yet shipped) · [Implemented] · [Rejected] (decided against, kept for the record) · [Retrospective] (analysis, no implementation) · [Promoted] (split into other logs) · [Superseded by #N] (model replaced). Older uncontested entries predate this convention — add a tag when you next touch the row.
Core Concepts & Architecture
| # | Title | Description |
|---|---|---|
| 00 | inspirations | Initial inspirations for the Jay project |
| 01 | what is Jay | Project overview: design-to-code, 3rd party UI inclusions, security |
| 27 | guiding principles of Jay | Core principles guiding the framework |
| 34 | jay stack | Full-stack framework design: rendering phases, component API |
| 68 | jay stack conceptual model | Conceptual model and architecture overview |
| 86 | jay stack full workflow lifecycle | Full lifecycle: setup → agent-kit → dev → render → refresh |
| 87 | jay-stack setup command | Plugin config templating, credential validation, reference generation |
Jay HTML & Templates
| # | Title | Description |
|---|---|---|
| 40 | changing jay-html format | Jay HTML format evolution |
| 44 | css support | CSS styling support in Jay |
| 46 | recursive jay-html | Recursive template support |
| 47 | recursive html context switching | Context switching in recursive templates |
| 57 | style binding support in jay-html | Dynamic style bindings |
| 71 | boolean attribute condition style parsing | Conditional style parsing |
| 75 | slow rendering jay-html to jay-html | Slow phase rendering transformations |
| 78 | unified condition parsing | Unified parsing for code generation and evaluation |
| 163 | built-in bindings and field comparison | jay.params, jay.url.path bindings; field-to-field === comparison; active menu pattern |
| 164 | inline style in body | Body <style> tags crash the template parser; skip, warn, or hoist to head |
| 165 | graceful expression parse errors | Convert expression parse errors to validation messages instead of crashing the page |
| 193 | binding across component composition boundaries | [Superseded by #196] — $parent binding + override binding + pure-component ref forwarding (Phases 1–4 shipped); composition model later retired by #196 |
| 194 | ref exposure and scoping across composition boundaries | [Superseded by #196] — slot contract tag as content-override target + two <override> forms (ref= merge, slot= content fill); Phase A shipped. Composition model retired by #196 |
| 195 | learnings from the composition boundary work | [Retrospective] on #181/#187/#193/#194 — one shared seam (the component runtime boundary), 10 silent wrong-render defects, +4884 lib/ lines; invariants V1–V6 for any replacement. Input to #196 |
| 196 | validated inline composition | [Implemented] — flatten a component's .jay-html into the page as a <jay:X> region (markup + @scope CSS), validated/synced against source; override is per-facet; one uniform headless-instance compile path. Replaces the #181/#187/#193/#194 composition model |
| 197 | makeJayComponent as a headless component | [Rejected] — proposed unifying regular-jay and jay-stack component models by splitting makeJayComponent; rejected because the divergence (code-first by-reference vs contract-first flattened) is intentional. jay-stack stays headless-only; headfull lives in lower-level Jay |
| 198 | free refs as boundary event sources | [Design] — resolves #196 Q12 (ref half): a region-body ref not in the contract (a "free ref") is auto-exposed as a typed event source on the region boundary; secure-mode-native, no page-scope compile path (supersedes #196 §7 for refs) |
| 200 | prefer design-system elements validation | [Implemented] — four default-on validate warnings enforcing "prefer design-system elements" (REGION-NOT-LINKED, COMPONENT-NO-TEMPLATE, REGION-OVERRIDE-NON-CONTENT, NO-DESIGN-SYSTEM); a content-tag allowlist classifies content edits vs. real overrides. Suppressible per-region/project |
| 201 | region system follow-ups | [Promoted] — holding pen for four #196/#200 follow-ups, split into #202, #203, #204 + a blog post |
| 202 | template-side content marker | [Design] — source-side jay-content marker declaring a template node a content slot: consumer edits there aren't drift and sync preserves them (the one inversion of #196 "unmarked ⇒ overwrite") |
| 203 | scope donut for region css isolation | [Design] — emit @scope (.ref) to (child-region-anchors) so a region's CSS stops at nested <jay:X> boundaries; coalescing key gains the to list |
| 204 | design-system index in the agent-kit | [Design] — generated agent-kit/design-system-index.yaml cataloging each headless component's contract + template variants, so agents discover what to flatten; feeds #200's REGION-NOT-LINKED |
| 205 | region variant selection | [Implemented] — as= import alias lets a page flatten two design variants of one contract (<jay:card> + <jay:feature-card>); resolution is tag-keyed so zero resolver change. Adds REGION-TAG-COLLISION + codegen import dedup |
| 206 | multi-root region css scoping | [Design] — multi-root regions can't style roots distinctly (.ref stamped on all roots, root selectors collapse to :scope). Always wrap region body in a display:contents .ref anchor (reusing the codegen wrapper convention) and delete the root→:scope rewrite |
| 207 | design-system coverage metrics | [Design] — report-only validate scorecard: per-page DS coverage % (elements in template=-backed regions ÷ total) + per-template reuse factor; computed in the existing validate loop, new ValidationResult fields, never fails the build |
| 208 | sync collapses multiline script bodies | [Bug] — sync→prettifyHtml flattens multi-line YAML script bodies to one line (prettify.ts:54-63); protection covers only jay-data. Multi-key jay-headless/jay-params break loudly, nested jay-validations suppressions drop silently. Fix: widen the verbatim-protect regex |
| 209 | region with css but no ref | [Implemented] — a region flattening a CSS-shipping template= with no ref emits its CSS unscoped; mergeScopeCss keeps only @scope blocks, so sync silently drops it. New REGION-CSS-NO-REF rule (checkRegionCssNoRef, mirrors checkNestedRegionRefs) — severity: error |
| 210 | broken internal link validation | [Implemented] (Check 1) — core validate pass (check-internal-links.ts) resolves every <a href> against concrete static routes + public assets → error on degenerate #/typo/missing-static-page; hrefs matching a dynamic pattern are deferred; per-page allow-broken-links suppression. Check 2 de-parked → DL#211 |
| 211 | build-output validation | [Implemented] — opt-in Tier 2 validate --tier-2 (check-build-output.ts) reads an existing build's route-manifest.json + per-instance *.cache.json (slow output) without running render: concrete-URL oracle (routes × instances) → error on dynamic-slug 404s (/design-log/wix/index); rendered-content/relative links → warning (markdown doubles as repo docs); per-instance meta/SEO via headMetaToHeadTags(headMeta, slowViewState) (unresolved {binding} = error, empty/over-length = warning). Own 📦 Tier 2 output group; --build-dir override; staleness = warning; Tier 1 (validate) stays the fast always-on tier and nudges toward Tier 2. Guide: designer/validation-tier-2-guide.md |
Contracts & Type System
| # | Title | Description |
|---|---|---|
| 35 | partial and complementary types | Type composition patterns |
| 38 | Contract File | Jay contract file format (YAML), ViewState and Refs types |
| 45 | View State Types | ViewState type system |
| 50 | rendering phases in contracts | Phase annotations (slow, fast, fast+interactive) for type safety |
| 51 | jay-html with contract references | Contract references in templates |
| 51 | Project Structure Identification | Pages vs Components identification |
| 61 | json-patch typed JSONPointer | Typed JSON operations |
| 79 | linked contracts with mixed phase properties | Linked sub-contracts across rendering phases |
| 95 | jay-action contract references | Reference contract ViewState types from .jay-action output schemas |
| 120 | record type in jay-action | record(T) type notation for typed Record maps in action schemas |
| 122 | enum name collision across linked contracts | Fix import shadowing and duplication when linked contracts share enum names |
| 152 | phase-aware contract props | Optional phase on props so the framework can validate binding availability |
| 189 | phase-aware prop resolution | [Implemented] — resolve each instance prop binding at its declared phase (completes #152); fixes fast/interactive bindings resolving to "" at SSR |
| 190 | instance prop type coercion | [Implemented] — coerce headless-instance props to their contract dataType at the serialization source so serialized __headlessInstances is typed; fixes client adoptBase … not found from raw attribute strings |
| 192 | enum value validation | [Implemented] — checkHeadlessInstanceProps validates enum instance props (resolves #187 Q8); fixes equalJayTypes to compare enums by ordered members |
Full-Stack Components & Rendering
| # | Title | Description |
|---|---|---|
| 36 | Partial Rendering | Partial/incremental rendering |
| 37 | Composite Component | Composite component patterns |
| 49 | full stack component rendering manifest | Manifest for full-stack rendering |
| 52 | jay-stack client-server code splitting | Client/server code splitting |
| 54 | render result monads | Result type patterns for rendering |
| 55 | full stack component parameter flow refinement | Props and parameter flow |
| 56 | deep merge view states with track-by | Array merging with track-by keys |
| 58 | jay-stack headless component resolution | Headless component resolution |
| 62 | relocate deep merge for stack-client-runtime | Client runtime deep merge |
| 72 | skip client script for non-interactive components | Optimization for static components |
| 84 | headless component props and repeater support | Props, multiple instances, forEach, jay: prefix |
| 85 | rendering phases and agent kit for agentic generation | Phases + contract/action discovery; agent-kit folder, markdown content → jay-html |
| 90 | headless instances in interactive forEach | Allow fast/interactive-only headless components inside forEach (no slow phase) |
| 111 | nested headfull full-stack components | Headfull components with own jay-html + SSR via headless pipeline template injection |
| 123 | deeply nested headfull and headless components | Gap analysis: headfull+keyed headless, headfull-in-headfull, headless-in-headfull |
| 141 | fast phase request context | Cookie access + response headers (Cache-Control) in fast phase for wix-members |
| 181 | headfull component override | [Superseded by #196] — usage-site override of a headfull component's markup via ref-anchored <override>; relaxes DL#51 extra-ref rule |
Server Actions & Client-Server Communication
| # | Title | Description |
|---|---|---|
| 63 | jay-stack server actions | RPC-style server actions: makeJayAction, makeJayQuery, action registry |
| 82 | automatic server-side action service injection | Auto-inject services when actions called from server code |
| 129 | streaming actions | makeJayStream with AsyncGenerator handlers, SSE transport |
| 131 | multipart file upload in actions | withFiles() opt-in for binary uploads via FormData, JayFile temp paths |
Plugin System
| # | Title | Description |
|---|---|---|
| 39 | Plugin package | Plugin package requirements and structure |
| 43 | Jay Package | Jay package format |
| 60 | plugin system refinement and dynamic contracts | Plugin.yaml, contract resolution, dynamic contract generation |
| 66 | transitive plugin dependency resolution | Plugin dependency resolution |
| 80 | exposing dynamic contracts for agentic generation | CLI and dev server contract generation for AI agents |
| 87 | jay-stack setup command | Plugin config templating, credential validation, references |
| 88 | PR 158 review guide | Review guide for export_import branch (Figma vendor + plugin resolution) |
| 89 | PR 158 merge concerns | Merge conflicts, duplicate work, and decisions for PR #158 into main |
| 130 | plugin routes and templates | Plugins provide pages (jay-html + page.ts) as routes; project overrides |
| 142 | plugin CLI commands | jay-stack run <plugin>/<command> for admin/batch operations |
| 145 | pluggable jay-html validation | Plugin-provided validation rules for jay-html with agent-friendly feedback |
| 147 | jay-html validation rules catalog | Complete catalog of all validation rules across wix-media, SEO, and a11y |
| 151 | design system validator plugin | Static CSS analysis against DESIGN.md tokens; replaces Happy DOM approach |
| 154 | plugin package shipping validation | Validate agent-kit directory is listed in package.json files |
| 155 | markdown plugin | Markdown rendering: directory-to-pages, inline content, code + mermaid |
| 156 | keyed headless component props | YAML body props for keyed headless components; consolidation with jay-params |
| 157 | interactive plugin setup | Interactive prompts in plugin setup handlers; move Wix logic out of create-jay |
| 159 | setup pipeline re-initialization | Re-init services after each plugin setup; suppress init noise; cascade deps |
| 160 | deprecate editor packages | Move editor-client/protocol/server to _deprecated; remove from stack-cli |
| 161 | markdown image url resolution | Rewrite relative image URLs in markdown; copy media to public; CDN mapping |
| 162 | structural headfull components | Allow headfull components without .ts code file; passthrough from contract |
| 187 | pure headfull components | [Superseded by #196] — three-tier headfull model; Tier 2 "pure headfull" components bind usage-site attributes to contract tags, variants drive own-template conditionals |
| 166 | a11y form and label validation rules | Extend a11y-validator: checkbox/radio, ARIA name integrity, duplicate ids, label hygiene |
| 167 | a11y nested interactive elements | a11y rule: focusable elements nested inside links/buttons (WCAG 4.1.2) |
| 184 | a11y adjacent-identical-text false positive on forEach siblings | Bug: adjacent-duplicate-text rule flattens complex subtrees and false-fires on items/loadedItems forEach siblings. Fix: only compare simple static elements — bail when either element's subtree (self/descendants) has a dynamic directive (forEach/if/when-*). Subsumes #185's guard |
| 185 | a11y adjacent-identical-text false positive on scoped bindings | Bug (extends #184): same rule false-fires on <label>{name}</label> next to <select><option forEach>{name}</option></select> and adjacent if-guarded product-options/product-modifiers divs. Guard-broadening now handled by #184's unified rule; this log's distinct fix: getVisibleText must honor descendant aria-hidden + suppression mechanism |
| 168 | font fallback metrics | Metric-matched fallback @font-face to prevent CLS on font load; validation + CLI tool |
| 169 | data files plugin | CSV/YAML/JSON/JSONL data source plugin: list view, item view, per-item pages, cross-references |
| 170 | seo validator false positives | Fix false positives: component vs page detection, html-string awareness, fetchpriority |
| 188 | viewport-height units break Google Search Console rendering | Design: validator flags unbounded vh/svh/lvh/dvh on top-level containers (Googlebot renders into a ~12k px viewport → distorted GSC screenshots). Structure-scoped via resolveCascade, not class names; excludes bounded/out-of-flow/media-scoped/height:100%. Detection in design-system-validator; fix decision in agent-kit |
| 171 | dev-only plugin routes | devOnly flag on plugin routes — dev-server tooling metadata on RouteInfo |
| 172 | plugin-framework-version-compatibility | Registry-based plugin↔framework compat; plugins compat, install preflight, doctor |
| 173 | aiditor-settings-plugin-contributions | Project settings tabs: template path, materialization, walk-up resolver, devOnly |
Services & Initialization
| # | Title | Description |
|---|---|---|
| 64 | client context initialization and plugin init | Client context and plugin initialization |
| 65 | makeJayInit builder pattern | Server initialization builder API |
| 67 | registerReactiveGlobalContext | Global reactive context registration |
Routing & Navigation
| # | Title | Description |
|---|---|---|
| 53 | jay-stack environment query parameter handling | Query parameter handling |
| 69 | route priority ordering for static vs dynamic routes | Route matching priority |
| 70 | static route param inference | Static route parameter inference (superseded by #113) |
| 113 | explicit route params for static overrides | Replace auto-inference with <script type="application/jay-params"> |
| 117 | fast phase query parameters | Type-safe query string access in fast phase only (props.query) |
| 163 | built-in bindings and field comparison | jay.params, jay.url.path bindings in page templates |
Compiler & Build System
| # | Title | Description |
|---|---|---|
| 04 | compiler | Initial compiler design |
| 20 | component compiler | Component compilation |
| 25 | building the compiler | Compiler architecture, code splitting |
| 28 | runtime compiler | Runtime compilation |
| 29 | algorithm to split safe code | Safe code splitting algorithm |
| 73 | jay-stack validate command | Plugin validation command |
| 74 | watch linked style files in dev server | Dev server file watching |
| 118 | jay-html-compiler refactor | Extract shared algorithms + split by compilation target |
| 134 | production build | Two-server production architecture: main server + slow render server |
| 134a | build pipeline | Per-instance compilation, shared chunks, Vite build strategy |
| 134b | main server | Production request handling: fast phase + SSR with pre-built artifacts |
| 134c | slow render server | Webhook invalidation, per-instance rebuild, versioned bucket building |
| 134d | server build | Compiling page.ts, actions, services, init.ts to production JS |
| 136 | loadParams route context | Passing inferred/route params to loadParams for multi-prefix filtering |
| 139 | wix deployment separation | Split build into frontend (CDN) + backend (container); Cloudflare-compatible fetch handler |
| 140 | production smoke test | Dedicated example project validating dev, production self-hosted, and production CDN modes |
| 143 | artifact store abstraction for BaaS | ArtifactStore interface, serve-only export, pre-imported modules for cloud deployment |
| 144 | per-route server elements | One server-element.js per route instead of per instance; render from ViewState, not literals |
| 145 | pluggable jay-html validation | Plugin-provided validation rules for jay-html files with agent-friendly feedback |
| 146 | css performance fixes | CSS minification in production build, preload hints for route CSS |
| 150 | build content hash | SHA-256 content hash of build output for deployment client/server sync |
| 153 | npm create jay | Interactive project scaffolding: name, plugin selection, agent-kit, setup banner |
| 158 | staged npm publish | Two-phase publish: stage all packages without OTP, then bulk-approve with single OTP |
| 147 | jay-html validation rules catalog | Complete catalog of all validation rules across wix-media, SEO, and a11y |
| 165 | graceful expression parse errors | Convert expression parse errors to validation messages instead of crashing the page |
| 166 | a11y form and label validation rules | Extend a11y-validator: checkbox/radio, ARIA name integrity, duplicate ids, label hygiene |
| 174 | undefined css variable validation | Validate that CSS var(--name) references have corresponding :root definitions |
| 175 | sitemap generation and robots validation | jay-stack sitemap command + robots.txt existence validation |
| 176 | validation warning suppression audit | Every warning must be suppressible; jay-validations script; promote some to errors |
| 177 | tree-shake unused plugin client bundles | Only preload shared chunks each page actually imports; per-route sharedDeps |
| 178 | compiler-free production runtime | Eliminate compiler deps from serve + rebuild; use page-parts.json for rebuild |
| 179 | compiler-free plugin runtime & capability-aware validation | Runtime (.) vs tools (./tools) entry split keeps compiler out of the serve bundle; actions vs commands; validate-plugin checks per declared capability |
| 180 | dev-only actions & production exclusion of dev-only surfaces | devOnly actions (handlers in ./tools) power settings pages; finishes DL#171 production exclusion of devOnly routes/actions |
| 182 | devOnly route client hydration imports the server bundle | DL#180 regression: devOnly route hydration imports ./tools (server) not ./client; browser pulls dev-server→fsevents → .node loader error. Fix: explicit clientCompPath |
| 183 | root headless instance not recognized in server element compiler | SSR generateServerElementFile renders a root <jay:contract> as a plain element (children bind to empty page ViewState → [SSR] data field not found); client/hydrate already special-case it. Breaks wix-members auth-callback. Fix: route root headless instance through renderServerElement |
| 186 | validator flags compiler-injected jc attribute as undeclared prop |
Bug: parseHeadfullFSImports injects jc="<contract>" on inlined .ts-backed headfull <jay:Name />; validator's prop check counts it as a user prop → false-positive "does not declare it as a prop" per page. Fix: add jc to HEADLESS_SKIP_ATTRS (validate-path only; style never reaches validate) |
Runtime & State Management
| # | Title | Description |
|---|---|---|
| 03 | runtime | Runtime architecture |
| 06 | state management | State management patterns |
| 08 | Jay Component | Component lifecycle and API |
| 22 | serialized mutable | Serialized mutable state |
| 30 | Jay Context API | Context API design |
| 31 | rename createState to createSignal | Signal-based reactivity |
| 32 | Reactive Pairing fixes | Reactive pairing fixes |
| 133 | html entities in text nodes | HTML entities decoded by SSR but not by client-side createTextNode/textContent |
Events & Interactivity
| # | Title | Description |
|---|---|---|
| 05 | events | Event handling |
| 09 | Safe events | Safe event handling |
| 13 | Redo Events | Event system redesign |
| 14 | References API | Element references API |
| 18 | update on conditional | Conditional updates |
| 24 | refactor refs | Reference system refactoring |
Security & Sandboxing
| # | Title | Description |
|---|---|---|
| 001 | 3rd party code problem | Third-party code security issues |
| 02 | Jay Element vs Component | Secure model comparison |
| 07 | nested components | Nested component security |
| 10 | building components - a challenge | Component building challenges |
| 12 | Secure Architecture | Security architecture |
| 15 | main to worker communication protocol | Worker communication |
| 16 | context api | Context API security |
| 17 | main and sandbox secure contexts | Secure context separation |
| 21 | alternative to context API | Context API alternatives |
Server-Side Rendering (SSR) & Hydration
| # | Title | Description |
|---|---|---|
| 11 | server side rendering | SSR design |
| 23 | JSON compare and patch | JSON diffing for SSR hydration |
| 48 | Jay Stack Services | Service injection for SSR |
| 50 | jay stack - headless configuration | Headless SSR configuration |
| 93 | client hydration | Hydrate server-rendered DOM: skip static HTML, adopt dynamic nodes |
| 94 | SSR streaming renderer | Compile jay-html to streaming server render, no DOM APIs |
| 98 | route-based server-element output | Server-element files follow route structure (consistent with DL96) |
| 99 | hydration coordinate alignment bugs | Fix forEach prefix, conditional+ref counter, containerCoordinate |
| 100 | hydrate conditional creation fallback | Level 3 hydration: create elements for false-at-SSR conditionals |
| 102 | headless instance SSR and hydration compilation | Server-element and hydrate targets for <jay:xxx> headless instances |
| 103 | coordinate pre-processing for SSR hydration consistency | Pre-assign jay-coordinate-base to all nodes; server and hydrate read it |
| 104 | hydration test plan | Test plan: static, conditionals, forEach, slowForEach, headless (a–d) |
| 106 | hydrate dynamic elements with Kindergarten | One Kindergarten per parent with mixed children; STATIC sentinel; _setGroup pattern |
| 107 | dev server consistency and phase optionality | Slow cache on/off parity, optional phases, SSR disable, build cleanup, loadParams cache |
| 108 | no-contract phase defaults for jay-stack | Without contract: all data is fast+interactive, no slow phase, remove noMainContract |
| 109 | unified dev server phase pipeline | Fix instance fast render gate for fast-only pages, hydration initial update |
| 110 | filesystem-based slow render cache | Cache loadParams per route, embed cache metadata in pre-rendered jay-html |
| 112 | hydration view state consistency | Hydrate with SSR ViewState (matches DOM), then update with client ViewState |
| 115 | slowForEachItem adopt element wrapping | Wrap slowForEachItem callback in adoptElement for multi-child nested slow forEach |
| 116 | client import rewriting in library builds | Fix bare @jay-framework/* imports not rewritten to /client in vite build output |
| 119 | async data SSR and hydration | Fix async data (Promise types) through SSR swap scripts, hydrate compiler, and ViewState serialization |
| 126 | coordinate assignment rules | Complete rules for coordinate assignment across forEach, slowForEach, headless, headfull nesting |
| 127 | SEO head injection | Render SEO data (title, meta, OG tags) from ViewState into <head> during SSR |
| 148 | head tag bindings | {binding} support in jay-html <title>, <meta>, <link> — resolved against ViewState at SSR time |
| 149 | script tags in jay-html | Reject inline scripts (use page.ts), allow external 3rd-party scripts in <head> |
| 135 | display contents for wrapper elements | Add display:contents to compiler-generated wrappers so they don't break sticky/flex/grid |
| 137 | production build self-containment | Strip headfull tags, source CSS refs, embed contracts, relative manifest paths — no src/ at runtime |
| 138 | safe refs stubs for unused contract refs | No-op proxy for contract-declared refs absent from template; prevents crashes in shared plugin code |
Developer Experience & Tooling
| # | Title | Description |
|---|---|---|
| 26 | jay start - compiling sandbox application |
Dev server startup |
| 33 | Jay 4 React | React integration |
| 41 | package naming migration to @jay-framework | Package naming convention |
| 42 | editor integration | Editor/IDE integration |
| 76 | AI Agent Integration | AI agent automation API |
| 77 | automation dev server integration | Automation API for dev tools |
| 80 | materializing dynamic contracts for agentic generation | CLI and dev server contract materialization for AI agents |
| 81 | dev server test mode | Health/shutdown endpoints and timeout for smoke testing |
| 83 | dev server logging and timing | Clean output, verbose mode, timing for render phases |
| 85 | rendering phases and agent kit for agentic generation | Agent-kit folder: instructions, contracts, markdown content with headless annotations |
| 91 | WebMCP plugin for jay-stack | Generic WebMCP support: automation→tools/resources/prompts, plugin packaging |
| 114 | documentation gaps and updates | Audit of docs vs design logs; gap list and update plan |
| 124 | contract props and params consistency | Ensure contracts declare props/params; agent-kit authoring docs + validate checks |
| 125 | plugin agent-kit | agent-kit --mode plugin for AI agents creating plugins (contracts, components, actions) |
| 128 | unfolded variant view | Page freeze: capture ViewState, render static SSR snapshots for side-by-side comparison |
| 179 | frozen page hmr on template change | Dev HMR reload for ?_jay_freeze full pages when jay-html/CSS changes; data stays frozen |
| 92 | Gemini agent plugin for jay-stack | Embedded AI agent: Gemini API, .jay-action metadata, chat contract, page automation |
| 97 | Contract-based tool descriptions for gemini agent | Semantic tool descriptions from .jay-contract via server action, not embedded in HTML |
| 132 | ui-kit headless primitives | Popover menu, scroll carousel, tab switcher, clipboard copy — thin JS over HTML/CSS |
| 142 | ui-kit Add Menu contribution | M19.3 add-menu yaml; U1–U3 done; ships with aiditor smoke |
Quick Lookup by Task
"I need to understand the rendering pipeline"
→ See #34 (jay stack), #50 (rendering phases), #52 (code splitting), #75 (slow rendering), #94 (SSR streaming)
"I'm working on contracts and types"
→ See #38 (Contract File), #45 (View State Types), #50 (phases in contracts), #79 (linked contracts)
"I'm adding server-side functionality"
→ See #63 (server actions), #48 (services), #65 (makeJayInit)
"I'm building or modifying a plugin"
→ See #39 (Plugin package), #60 (plugin system refinement), #66 (plugin dependencies), #84 (headless component props)
"I'm working with headless components"
→ See #50 (headless configuration), #58 (headless resolution), #84 (props, multiple instances, jay: prefix), #90 (forEach instances without slow phase)
"I'm composing components into a page (overrides, slots, refs across boundaries)"
→ Start with #195 (retrospective: why the reference-based model was retired) and #196 (the replacement: materialise + validate)
→ Then #198 (free refs → boundary event sources: page-owned refs inside a region). (#197 — generalizing the flatten model to regular jay — was rejected; jay-stack stays headless-only, headfull lives in the lower-level Jay runtime)
→ History: #111 (nested headfull FS), #162 (structural), #181 (override), #187 (three-tier), #193 ($parent + ref forwarding), #194 (slots + Tier 2 inlining)
"I'm working on the compiler"
→ See #25 (building the compiler), #28 (runtime compiler), #29 (code splitting), #78 (condition parsing)
"I'm adding client-side interactivity"
→ See #06 (state management), #31 (createSignal), #30 (Context API), #09 (safe events), #93 (client hydration)
"I'm working on SSR or hydration"
→ See #11 (SSR concept), #93 (client hydration), #94 (SSR streaming renderer), #75 (slow rendering), #72 (skip client script), #106 (Kindergarten for mixed children)
"I'm working on the dev server"
→ See #26 (jay start), #74 (file watching), #77 (automation integration), #81 (test mode), #107 (consistency and phase optionality), #128 (page freeze), #179 (frozen page HMR on template change)
"I need to understand security model"
→ See #001 (3rd party problem), #12 (Secure Architecture), #17 (secure contexts)
"I'm working on AI agent integration"
→ See #76 (AI Agent Integration), #77 (automation dev server), #80 (contract materialization for agents), #85 (agent kit and rendering phases), #91 (WebMCP plugin), #92 (Gemini agent plugin)
→ Agent kit skills: .cursor/skills/jay-agent-kit/ (main), jay-html-authoring/, jay-cli-commands/, jay-contracts-and-plugins/, jay-dev-server-test/
"I need to understand the full workflow lifecycle"
→ See #86 (full workflow lifecycle: setup → agent-kit → coding → slow → fast → interactive → refresh)
"I'm working on the production build"
→ See #134 (production build: two-server architecture, build pipeline, artifact layout)
Notes
- Design logs are not updated after initial writing - they capture decisions at a point in time
- Implementation may deviate from original design - check "Implementation Results" sections
- Some logs have multiple files with the same number (e.g., 50, 51) - these are related but separate topics
- Diagram files (.mmd, .svg, .png) accompany some design logs for visual reference
Log Methodology Note
Note: These design logs are written primarily for AI agents as part of the Design Log methodology and made accessible here for human readers. The language and structure are optimized for machine consumption — expect precise, specification-style prose rather than narrative documentation.