jails-js 6.9.7 → 6.9.9

package/ai/examples.md

@@ -0,0 +1,199 @@
+# Canonical Examples
+
+## Register and Start
+
+```ts
+import { register, start } from 'jails-js'
+import * as helloWorld from './components/hello-world'
+
+register('hello-world', helloWorld)
+start()
+```
+
+## Counter Markup
+
+```html
+<hello-world>
+  <h1>Hello World!</h1>
+  <p>A simple Counter</p>
+  <button class="btn add">+</button>
+  <span html-inner="counter">0</span>
+  <button class="btn subtract">-</button>
+</hello-world>
+```
+
+## Counter Component
+
+```ts
+export default function helloWorld({ main, on, state }) {
+  main(() => {
+    on('click', 'button.add', add)
+    on('click', 'button.subtract', subtract)
+  })
+
+  const add = () => {
+    state.set(s => {
+      s.counter += 1
+    })
+  }
+
+  const subtract = () => {
+    state.set(s => {
+      s.counter -= 1
+    })
+  }
+}
+
+export const model = {
+  counter: 0
+}
+```
+
+## Conditional Rendering
+
+```html
+<my-component>
+  <div html-if="show">Hello, {{ name }}</div>
+  <div html-if="!show">I'm hidden!</div>
+</my-component>
+```
+
+```ts
+state.set({ name: 'Clark Kent', show: true })
+```
+
+## Loop Rendering
+
+```html
+<my-component>
+  <ul>
+    <li html-for="item in list">
+      <span html-if="item.show">{{ item.name }} {{ $index }}</span>
+    </li>
+  </ul>
+</my-component>
+```
+
+## Attribute Binding
+
+```html
+<my-component html-class="loading ? 'is-loading' : ''">
+  <img html-src="imageUrl" alt="">
+</my-component>
+```
+
+## Static Third-Party Region
+
+```html
+<app-swiper>
+  <input type="number" value="1" min="1" max="9" html-static>
+  <p>Chosen page: {{ page }}</p>
+  <div class="swiper mySwiper" html-static>
+    <div class="swiper-wrapper">
+      <div class="swiper-slide">Slide 1</div>
+      <div class="swiper-slide">Slide 2</div>
+    </div>
+  </div>
+</app-swiper>
+```
+
+```ts
+import Swiper from 'swiper'
+
+export default function appSwiper({ main, on, elm, state }) {
+  const wrapper = elm.querySelector('.swiper')
+  const swiper = new Swiper(wrapper)
+
+  main(() => {
+    on('input', 'input[type=number]', goTo)
+  })
+
+  const goTo = e => {
+    const page = Number(e.target.value) || 1
+    swiper.slideTo(page - 1)
+    state.set({ page })
+  }
+}
+
+export const model = {
+  page: 1
+}
+```
+
+## Dependency Injection
+
+```ts
+import { register } from 'jails-js'
+import http from './shared/http'
+import * as myComponent from './components/my-component'
+
+register('my-component', myComponent, { http })
+```
+
+```ts
+export default function myComponent({ main, dependencies }) {
+  const { http } = dependencies
+
+  main(() => {
+    // use http
+  })
+}
+```
+
+## View Function
+
+```ts
+export const view = state => ({
+  ...state,
+  biggerThen10: state.counter > 10 ? 'bigger' : ''
+})
+```
+
+```html
+<div html-class="biggerThen10">{{ counter }}</div>
+```
+
+## Embedded Template
+
+```ts
+import { html, attributes } from 'jails-js/html'
+
+export const template = ({ children }) => html`
+  ${children}
+  <div>{{ counter }}</div>
+  <button data-add ${attributes({ id: 'my-button-id' })}>+</button>
+`
+```
+
+## Global Pub/Sub
+
+```ts
+export default function producer({ main, on, publish }) {
+  main(() => {
+    on('click', 'button', doSomething)
+  })
+
+  const doSomething = () => {
+    fetch('/service')
+      .then(response => response.json())
+      .then(data => publish('my-component:fetched', data))
+  }
+}
+```
+
+```ts
+export default function consumer({ main, subscribe, unmount }) {
+  let unsubscribe
+
+  main(() => {
+    unsubscribe = subscribe('my-component:fetched', data => {
+      console.log(data)
+    })
+  })
+
+  unmount(() => {
+    if (unsubscribe) unsubscribe()
+  })
+}
+```
+

package/ai/faq.md

@@ -0,0 +1,70 @@
+# FAQ
+
+## What is Jails?
+
+Jails is a JavaScript framework for enhancing custom elements in existing HTML. Components are behavior modules attached to DOM islands.
+
+## Does Jails require client-side rendering for the whole page?
+
+No. The documented model favors SSR, SSG, CMS, or static HTML for first paint, then Jails enhances selected components.
+
+## How do updates happen?
+
+Use `state.set()`. Jails updates directive-managed DOM and resolves the returned Promise after the DOM update cycle.
+
+## Is `state.set()` synchronous?
+
+Do not rely on synchronous DOM updates. Use `state.set(...).then(...)` for post-render work.
+
+## How does event delegation work?
+
+`on(event, selector, callback)` attaches listening behavior to the component root and matches child elements by selector. Use `event.delegateTarget` to access the matched element.
+
+## When should I use `emit()`?
+
+Use `emit()` for child-to-parent or local DOM-tree communication. It dispatches bubbling custom events.
+
+## When should I use `publish()` and `subscribe()`?
+
+Use global pub/sub for components in different DOM trees where bubbling DOM events do not provide a natural path.
+
+## How should stores be structured?
+
+Use component-local state as the default. Parent components may pass props down. Use global pub/sub for messages, not as a hidden global state replacement unless the application deliberately builds that layer.
+
+## How do directives interact?
+
+Nested directives evaluate inside the scope of their parent. `html-for` adds item variables such as the item alias and `$index`; nested `html-if` can conditionally render content per item. `html-static` stops updates for its node and children.
+
+## How does `html-if` affect DOM state?
+
+Falsy conditions remove the node from rendered output according to docs examples. Treat state inside that subtree as discarded when removed.
+
+## How does `html-for` preserve items?
+
+The docs do not specify keyed reconciliation. Assume repeated output is based on iterable order. Avoid relying on per-item DOM preservation unless verified against runtime source.
+
+## Why use `html-static`?
+
+Use it when a subtree is immutable, browser-owned, or mutated by an external library. Jails skips diffing the node and children.
+
+## What are boolean `html-*` attributes?
+
+Attributes such as `selected`, `checked`, `readonly`, `disabled`, and `autoplay` are present for truthy expressions and removed for falsy expressions.
+
+## What is the difference between `html-inner` and mustache?
+
+Both output expression values. `html-inner` targets a specific element and allows fallback content before JavaScript mounts.
+
+## How do I avoid mustache placeholders flashing before mount?
+
+Use server-rendered fallback content with `html-inner`, or place data-dependent fragments inside native `<template>`.
+
+## How do reusable components receive services?
+
+Pass services through `register(name, module, dependencies)` and read them from the component `dependencies` helper.
+
+## How should cleanup work?
+
+Register cleanup with `unmount()` for subscriptions, timers, observers, and third-party library instances.
+

package/ai/glossary.md

@@ -0,0 +1,28 @@
+# Glossary
+
+- Component: a JavaScript module attached to each matching custom element instance.
+- Controller: the default export function of a component module.
+- Model: required export that initializes component state.
+- View: optional export that maps state to render-only values.
+- Template: optional export that returns embedded HTML for a component.
+- Directive: an HTML attribute interpreted by Jails, such as `html-if` or `html-for`.
+- Mustache: default interpolation syntax `{{ expression }}`.
+- Render scope: object used to evaluate directives and mustache expressions, normally state transformed by `view`.
+- State: component-local mutable data managed by the `state` helper.
+- `state.set`: method that updates state and schedules DOM updates.
+- Next tick: work performed after `state.set()` resolves its Promise.
+- Event delegation: listening at the component root and matching child selectors.
+- `delegateTarget`: Jails-added event property containing the matched delegated element.
+- Static boundary: a node marked `html-static` whose subtree is skipped by Jails updates.
+- Logic featured component: component that supplies behavior for externally provided HTML.
+- Fully featured component: component that includes embedded HTML via `template`.
+- Dependency injection: passing dependencies through `register()` to the component `dependencies` helper.
+- Pub/sub: global publish/subscribe communication for components in separate DOM trees.
+- `emit`: helper for bubbling DOM CustomEvents upward.
+- `trigger`: helper for programmatically dispatching events.
+- `effect`: lifecycle helper for reacting to parent prop updates.
+- `unmount`: lifecycle helper for cleanup when the component element is detached.
+- SSR: server-side rendering. Jails can enhance SSR HTML.
+- SSG: static site generation. Jails can enhance static HTML.
+- Island: a focused interactive region inside a mostly static page.
+

package/ai/json/api.json

@@ -0,0 +1,190 @@
+[
+  {
+    "name": "register",
+    "signature": "register(name: string, module: Module, dependencies?: object): void",
+    "description": "Registers a component module for a custom element name.",
+    "parameters": ["name: custom element tag", "module: component module namespace", "dependencies: optional injected dependencies"],
+    "returnValue": "Not documented.",
+    "sideEffects": ["Stores component registration."],
+    "lifecycleImplications": "Call before start() for components that should bootstrap in that scan.",
+    "examples": ["register('my-component', myComponent, { http })"],
+    "relatedApis": ["start", "dependencies"]
+  },
+  {
+    "name": "start",
+    "signature": "start(target?: HTMLElement): void",
+    "description": "Scans a DOM target for registered components and bootstraps them.",
+    "parameters": ["target: optional scan root; defaults to document.body"],
+    "returnValue": "Not documented.",
+    "sideEffects": ["Creates component instances.", "Runs component bootstrap."],
+    "lifecycleImplications": "Can be called multiple times but should not be called unnecessarily.",
+    "examples": ["register('hello-world', helloWorld); start()"],
+    "relatedApis": ["register"]
+  },
+  {
+    "name": "templateConfig",
+    "signature": "templateConfig({ tags: [string, string] }): void",
+    "description": "Changes global mustache delimiters.",
+    "parameters": ["tags: opening and closing delimiter strings"],
+    "returnValue": "Not documented.",
+    "sideEffects": ["Changes template parser configuration."],
+    "lifecycleImplications": "Call before templates are processed.",
+    "examples": ["jails.templateConfig({ tags: ['@{', '}'] })"],
+    "relatedApis": ["mustache"]
+  },
+  {
+    "name": "publish",
+    "signature": "publish(name: string, data?: any): void",
+    "description": "Publishes a global pub/sub event.",
+    "parameters": ["name: event name", "data: optional payload"],
+    "returnValue": "Not documented.",
+    "sideEffects": ["Invokes global subscribers."],
+    "lifecycleImplications": "Use for cross-tree communication.",
+    "examples": ["publish('my-component:fetched', data)"],
+    "relatedApis": ["subscribe"]
+  },
+  {
+    "name": "subscribe",
+    "signature": "subscribe(name: string, fn: Function): Function",
+    "description": "Subscribes to a global pub/sub event.",
+    "parameters": ["name: event name", "fn: callback"],
+    "returnValue": "Unsubscribe function.",
+    "sideEffects": ["Registers global listener."],
+    "lifecycleImplications": "Call unsubscribe in unmount() when tied to component lifetime.",
+    "examples": ["const unsubscribe = subscribe('my-component:fetched', handler)"],
+    "relatedApis": ["publish", "unmount"]
+  },
+  {
+    "name": "html",
+    "signature": "html(strings: TemplateStringsArray, ...values: any[]): string",
+    "description": "Template string helper for component templates.",
+    "parameters": ["template string parts", "interpolated values"],
+    "returnValue": "HTML string.",
+    "sideEffects": [],
+    "lifecycleImplications": "Used by template exports.",
+    "examples": ["html`<section>${children}</section>`"],
+    "relatedApis": ["template", "attributes"]
+  },
+  {
+    "name": "attributes",
+    "signature": "attributes(values: Record<string, any>): string",
+    "description": "Serializes attributes for template strings.",
+    "parameters": ["values: object of attributes"],
+    "returnValue": "Attribute string.",
+    "sideEffects": [],
+    "lifecycleImplications": "Used when constructing template HTML.",
+    "examples": ["attributes({ id: 'my-button-id' })"],
+    "relatedApis": ["html", "template"]
+  },
+  {
+    "name": "main",
+    "signature": "main(fn: Function): void",
+    "description": "Registers mount-time component entrypoint.",
+    "parameters": ["fn: callback"],
+    "returnValue": "void",
+    "sideEffects": ["Runs callback after component mount."],
+    "lifecycleImplications": "Use for event registration and initial actions.",
+    "examples": ["main(() => { on('click', '[data-add]', add) })"],
+    "relatedApis": ["on"]
+  },
+  {
+    "name": "state.set",
+    "signature": "state.set(newprops: object): Promise<object> | state.set((currentState: object) => void): Promise<object>",
+    "description": "Updates component-local state and schedules DOM update.",
+    "parameters": ["newprops object or mutator function"],
+    "returnValue": "Promise resolving after DOM update.",
+    "sideEffects": ["Mutates component state.", "Updates directive-managed DOM."],
+    "lifecycleImplications": "Use returned Promise for next-tick work.",
+    "examples": ["state.set({ isVisible: false })", "state.set(s => { s.counter += 1 })"],
+    "relatedApis": ["state.get", "view"]
+  },
+  {
+    "name": "state.get",
+    "signature": "state.get(): object",
+    "description": "Returns current component state.",
+    "parameters": [],
+    "returnValue": "Current state object.",
+    "sideEffects": [],
+    "lifecycleImplications": "Use for snapshots before optimistic updates.",
+    "examples": ["const current = state.get()"],
+    "relatedApis": ["state.set"]
+  },
+  {
+    "name": "state.protected",
+    "signature": "state.protected(props: Array<string>): void",
+    "description": "Prevents selected child props from being overwritten by parent updates.",
+    "parameters": ["props: property names"],
+    "returnValue": "void",
+    "sideEffects": ["Changes parent-prop update behavior for listed props."],
+    "lifecycleImplications": "Call during component setup before relevant parent updates.",
+    "examples": ["state.protected(['counter'])"],
+    "relatedApis": ["effect"]
+  },
+  {
+    "name": "on",
+    "signature": "on(event: string, cssSelector: string, callback: Function): void",
+    "description": "Registers component-scoped delegated event or attribute-change listener.",
+    "parameters": ["event or attribute pattern", "cssSelector", "callback"],
+    "returnValue": "void",
+    "sideEffects": ["Attaches delegated listener at component boundary."],
+    "lifecycleImplications": "Register inside main().",
+    "examples": ["on('click', '[data-add]', add)", "on('[src]', 'iframe', iframeSrcChange)"],
+    "relatedApis": ["off", "emit", "trigger"]
+  },
+  {
+    "name": "off",
+    "signature": "off(event: string, callback: Function): void",
+    "description": "Removes an event listener.",
+    "parameters": ["event", "callback"],
+    "returnValue": "void",
+    "sideEffects": ["Detaches listener."],
+    "lifecycleImplications": "Use for manual listener cleanup.",
+    "examples": ["off('click', componentClick)"],
+    "relatedApis": ["on"]
+  },
+  {
+    "name": "emit",
+    "signature": "emit(event: string, data?: any): void",
+    "description": "Emits a bubbling DOM CustomEvent from the component.",
+    "parameters": ["event", "data"],
+    "returnValue": "void",
+    "sideEffects": ["Dispatches DOM event."],
+    "lifecycleImplications": "Use for child-to-parent communication.",
+    "examples": ["emit('time-elapsed', '10 seconds elapsed')"],
+    "relatedApis": ["on", "trigger"]
+  },
+  {
+    "name": "trigger",
+    "signature": "trigger(event: string, data?: object): void | trigger(event: string, selector: string, data?: object): void",
+    "description": "Programmatically dispatches an event from the component or selected child.",
+    "parameters": ["event", "optional selector", "optional data"],
+    "returnValue": "void",
+    "sideEffects": ["Dispatches event."],
+    "lifecycleImplications": "Useful for component-mediated event flows.",
+    "examples": ["trigger('click', { someparam: true })", "trigger('click', 'button', { anotherparam: true })"],
+    "relatedApis": ["on", "emit"]
+  },
+  {
+    "name": "effect",
+    "signature": "effect(callback: Function): void | Promise<any>",
+    "description": "Registers sync or async reaction to parent prop updates.",
+    "parameters": ["callback receiving props"],
+    "returnValue": "void or Promise depending on callback.",
+    "sideEffects": ["Can override or compose parent props."],
+    "lifecycleImplications": "Runs when parent props change.",
+    "examples": ["effect(async props => { props.count += 1 })"],
+    "relatedApis": ["state.protected"]
+  },
+  {
+    "name": "unmount",
+    "signature": "unmount(callback: Function): void",
+    "description": "Registers cleanup for component element detachment.",
+    "parameters": ["callback"],
+    "returnValue": "void",
+    "sideEffects": ["Runs cleanup on detach."],
+    "lifecycleImplications": "Use for subscriptions, observers, timers, and widgets.",
+    "examples": ["unmount(() => unsubscribe())"],
+    "relatedApis": ["subscribe"]
+  }
+]
+

package/ai/json/directives.json

@@ -0,0 +1,107 @@
+[
+  {
+    "name": "html-if",
+    "description": "Conditionally renders a node from a JavaScript expression evaluated against component render scope.",
+    "syntax": "<div html-if=\"show\">...</div>",
+    "renderingBehavior": "Truthy expressions render the node; falsy expressions remove it from rendered output.",
+    "domBehavior": "Node is created when condition becomes truthy and removed when falsy. DOM state inside removed branch is lost.",
+    "updateBehavior": "Re-evaluated after state updates and parent prop updates.",
+    "examples": ["<p html-if=\"isVisible\">Visible</p>"],
+    "rules": ["Keep condition expressions cheap.", "Use delegated events for children inside conditional branches."],
+    "relatedConcepts": ["state.set", "render scope", "conditional rendering"],
+    "antiPatterns": ["Using for large frequently toggled subtrees when DOM state must persist.", "Side effects in condition expressions."],
+    "performanceNotes": "Branch creation/removal cost grows with subtree size and nested directives."
+  },
+  {
+    "name": "html-for",
+    "description": "Repeats an element for each item in an array or object.",
+    "syntax": "<li html-for=\"item in list\">{{ item.name }}</li>",
+    "renderingBehavior": "The directive element acts as the repeated template. Each iteration receives the item alias, $index, and $key.",
+    "domBehavior": "Copies are inserted at the directive position. Extra copies are removed when iterable shrinks.",
+    "updateBehavior": "Re-evaluated after state changes. Keyed reconciliation is not documented; assume order-based behavior.",
+    "examples": ["<li html-for=\"item in list\"><span html-if=\"item.show\">{{ item.name }} {{ $index }}</span></li>"],
+    "rules": ["Avoid expensive filtering/sorting in directive expression.", "Use event delegation instead of per-item listeners."],
+    "relatedConcepts": ["loops", "$index", "$key", "event delegation"],
+    "antiPatterns": ["Deeply nested loops.", "Relying on undocumented keyed DOM preservation."],
+    "performanceNotes": "Cost grows with item count and nested directive complexity."
+  },
+  {
+    "name": "html-inner",
+    "description": "Writes an expression result into a specific element, replacing fallback content after mount.",
+    "syntax": "<span html-inner=\"counter\">0</span>",
+    "renderingBehavior": "Equivalent purpose to mustache interpolation but targeted at one element.",
+    "domBehavior": "Existing child content is replaced with expression output.",
+    "updateBehavior": "Re-evaluated after state changes.",
+    "examples": ["<strong html-inner=\"name\">Some default value</strong>"],
+    "rules": ["Use for scalar content and progressive fallback text."],
+    "relatedConcepts": ["mustache", "fallback content", "state"],
+    "antiPatterns": ["Injecting untrusted HTML.", "Using for complex nested markup."],
+    "performanceNotes": "Cheap for text/scalar updates because element structure remains stable."
+  },
+  {
+    "name": "html-model",
+    "description": "Provides initial component state from markup.",
+    "syntax": "<my-component html-model=\"{ counter: 5 }\"></my-component>",
+    "renderingBehavior": "Initial state includes html-model values, overriding model props as documented.",
+    "domBehavior": "Initialization directive; not intended as a final application attribute.",
+    "updateBehavior": "Used during bootstrap, not reactive after mount.",
+    "examples": ["<my-component html-model=\"{ counter: 5 }\"><span html-inner=\"counter\"></span></my-component>"],
+    "rules": ["Use for small per-instance configuration.", "Use valid JavaScript object expression syntax."],
+    "relatedConcepts": ["model", "initialState"],
+    "antiPatterns": ["Large serialized payloads in attributes.", "Treating html-model as reactive."],
+    "performanceNotes": "Cheap bootstrap mechanism; avoid parsing large attribute payloads."
+  },
+  {
+    "name": "html-*",
+    "description": "Binds standard HTML attributes to JavaScript expressions while stripping the html- prefix.",
+    "syntax": "<img html-src=\"imageUrl\" alt=\"\">",
+    "renderingBehavior": "Expression result is written to the real attribute name.",
+    "domBehavior": "Boolean attributes are present for truthy values and removed for falsy values.",
+    "updateBehavior": "Re-evaluated after state changes.",
+    "examples": ["<div html-class=\"loading ? 'is-loading' : ''\"></div>", "<button html-disabled=\"isSaving\">Save</button>"],
+    "rules": ["Use html-src to avoid premature network requests.", "Treat selected, checked, readonly, disabled, and autoplay as boolean attributes."],
+    "relatedConcepts": ["attribute binding", "boolean attributes", "attribute observers"],
+    "antiPatterns": ["Expecting disabled=\"false\" for falsy booleans.", "Complex class logic inline."],
+    "performanceNotes": "Efficient for scalar attributes; heavy expressions repeat on updates."
+  },
+  {
+    "name": "html-static",
+    "description": "Marks a node and children as skipped by Jails virtual DOM updates/diffing.",
+    "syntax": "<div html-static>...</div>",
+    "renderingBehavior": "The marked subtree is excluded from Jails template updates.",
+    "domBehavior": "Browser or external libraries may mutate the subtree without Jails reconciling it.",
+    "updateBehavior": "State updates skip the subtree. Directives inside should be treated as inert after the static boundary.",
+    "examples": ["<div class=\"swiper\" html-static></div>", "<input type=\"number\" value=\"1\" html-static>"],
+    "rules": ["Use for third-party DOM libraries.", "Use for browser-owned form values when state does not need every keystroke."],
+    "relatedConcepts": ["DOM ownership", "third-party integration", "diff boundary"],
+    "antiPatterns": ["Expecting dynamic content inside html-static to update.", "Marking too much of a component static."],
+    "performanceNotes": "Reduces diff work and prevents conflicts with imperative DOM mutation."
+  },
+  {
+    "name": "mustache",
+    "description": "Interpolates JavaScript expression results into text positions.",
+    "syntax": "{{ expression }}",
+    "renderingBehavior": "Expression result becomes text/content at the interpolation position.",
+    "domBehavior": "Text node content changes when expression result changes.",
+    "updateBehavior": "Re-evaluated after state updates. Delimiters can be changed with templateConfig.",
+    "examples": ["<p>Hello, {{ name }}</p>"],
+    "rules": ["Use for scalar output.", "Move formatting into view for clarity."],
+    "relatedConcepts": ["templateConfig", "view", "render scope"],
+    "antiPatterns": ["Side effects in expressions.", "Large logic in interpolation."],
+    "performanceNotes": "Cheap for simple text; complex expressions repeat during updates."
+  },
+  {
+    "name": "template element",
+    "description": "Native inert HTML used to hide dynamic fragments from initial page rendering.",
+    "syntax": "<template><div html-if=\"user\">{{ user.name }}</div></template>",
+    "renderingBehavior": "Browser does not render template contents directly.",
+    "domBehavior": "Content stays inert until processed/cloned by template system.",
+    "updateBehavior": "Useful for fragments that require data before display.",
+    "examples": ["<template><div html-if=\"userData\">Welcome, {{ userData.name }}!</div></template>"],
+    "rules": ["Use for data-dependent fragments that should not flash markers."],
+    "relatedConcepts": ["progressive enhancement", "mustache", "first paint"],
+    "antiPatterns": ["Hiding SSR content that should appear immediately."],
+    "performanceNotes": "Improves first-paint correctness, not a diff optimization by itself."
+  }
+]
+

package/ai/json/patterns.json

@@ -0,0 +1,69 @@
+[
+  {
+    "name": "Progressive Island Component",
+    "description": "Enhance server-rendered or static custom element HTML with Jails behavior.",
+    "intent": "Keep first paint outside client-side rendering while adding focused interactivity.",
+    "structure": ["custom element HTML", "component module", "register()", "start()"],
+    "examples": ["<hello-world><span html-inner=\"counter\">0</span></hello-world>"],
+    "rules": ["HTML owns initial structure.", "Controller owns behavior.", "State owns render data."],
+    "relatedConcepts": ["SSR", "SSG", "custom element", "directives"],
+    "antiPatterns": ["Rendering all content only after JavaScript when static HTML is available."],
+    "performanceNotes": "Reduces client JavaScript and avoids full-page hydration."
+  },
+  {
+    "name": "Page-Scoped Store",
+    "description": "Keep mutable page or island state in the component model/state helper.",
+    "intent": "Make state ownership explicit and local.",
+    "structure": ["model defines data/loading/error", "controller updates with state.set", "template renders directives"],
+    "examples": ["export const model = { items: [], loading: false, error: null }"],
+    "rules": ["Define all state keys in model.", "Use parent props for child data.", "Use pub/sub only for cross-tree messages."],
+    "relatedConcepts": ["state", "model", "parent props"],
+    "antiPatterns": ["Hidden global mutable state shared by many components."],
+    "performanceNotes": "Constrains update work to component boundaries."
+  },
+  {
+    "name": "Services Through Dependencies",
+    "description": "Inject reusable services through register dependencies.",
+    "intent": "Keep generic components free from application-specific imports.",
+    "structure": ["register('component', module, { service })", "controller reads dependencies.service"],
+    "examples": ["register('form-validation', formValidation, { validations, masks })"],
+    "rules": ["Inject app-specific rules.", "Import only truly generic dependencies directly."],
+    "relatedConcepts": ["dependencies", "services", "register"],
+    "antiPatterns": ["Bundling every country-specific validation in a generic form component."],
+    "performanceNotes": "Avoids unused library code and supports reusable packages."
+  },
+  {
+    "name": "Delegated Event Handling",
+    "description": "Attach listeners at component root and match child selectors.",
+    "intent": "Keep listeners stable across DOM replacement.",
+    "structure": ["main()", "on(event, selector, handler)", "event.delegateTarget"],
+    "examples": ["on('click', '[data-remove]', remove)"],
+    "rules": ["Use stable data attributes.", "Read delegateTarget, not target."],
+    "relatedConcepts": ["on", "off", "delegateTarget", "html-for"],
+    "antiPatterns": ["One listener per repeated item."],
+    "performanceNotes": "Reduces listener count and rebinding cost."
+  },
+  {
+    "name": "Static Third-Party Integration",
+    "description": "Mark externally mutated DOM with html-static.",
+    "intent": "Prevent Jails diffing from conflicting with imperative libraries.",
+    "structure": ["html-static widget root", "controller initializes library", "state renders surrounding UI"],
+    "examples": ["<div class=\"swiper\" html-static></div>"],
+    "rules": ["Do not expect directives inside static subtree to update.", "Keep static boundary as small as practical."],
+    "relatedConcepts": ["html-static", "DOM ownership", "innerHTML"],
+    "antiPatterns": ["Third-party DOM mutation in Jails-managed subtree."],
+    "performanceNotes": "Skips diffing and protects library-managed DOM."
+  },
+  {
+    "name": "Parent-Child DOM Event Communication",
+    "description": "Children emit bubbling events; parents listen with delegated on().",
+    "intent": "Use native DOM topology for local component communication.",
+    "structure": ["child emit(name, payload)", "parent on(name, selector, handler)"],
+    "examples": ["emit('item-selected', item)"],
+    "rules": ["Use emit for upward local events.", "Use pub/sub for disconnected trees."],
+    "relatedConcepts": ["emit", "on", "publish", "subscribe"],
+    "antiPatterns": ["Global pub/sub for direct child-parent messages."],
+    "performanceNotes": "Narrower event scope than global channels."
+  }
+]
+