Sercrod AI Start Here

Read this file before ai-runtime-rules.md and ai-directives.md.

Sercrod exists to add explicit data flow and behavior to existing HTML without requiring a virtual DOM or transferring ownership of the whole page to an application framework. It is especially useful when humans, generators, and AI must be able to see where values come from, where results go, which external capability is requested, and where rendered content belongs.

Sercrod declarations answer four questions:

1. Where to read from — the declared data or external source.
2. Where to write to — the declared data, DOM, storage, or response target.
3. Which capability to use — the directive requests a named capability; its role-mapped adapter performs environment-specific work.
4. Where to place it — the host, element, or placement region in existing HTML.

Do not invent syntax from these examples. After choosing a pattern, inspect its linked reference, use the Sercrod completion helper, and check the result.

P1: Existing HTML binding

Stable ID: existing-html-binding

Use this pattern to connect ordinary form controls and existing output elements to visible host data. The HTML remains the primary structure.

• Read from: the existing input element.
• Write to: form.name in host data.
• Capability: ordinary input and DOM output; no external adapter.
• Place in: the existing label and greeting paragraph.

<serc-rod id="profile" data='{"form":{"name":"Alice"}}'>
  <form>
    <label>
      Name
      <input type="text" *input="form.name">
    </label>
  </form>

  <p>Hello, <span *print="form.name"></span>.</p>
</serc-rod>

Next: directives/input.md, directives/print.md, and the input-timing reference.

P2: Structure and placement

Stable ID: structure-and-placement

Use this pattern when data should repeat, select, or place content inside an existing region. Sercrod owns only the declared structural operation.

• Read from: items in host data.
• Write to: repeated list-item output.
• Capability: structural rendering; no external adapter.
• Place in: the existing <ul>; its heading and surrounding section remain.

<section class="catalog">
  <h2>Current items</h2>

  <serc-rod data='{"items":["Apple","Banana","Cherry"]}'>
    <ul class="existing-list">
      <li *for="item of items">
        <span *print="item"></span>
      </li>
    </ul>
  </serc-rod>

  <p class="existing-footer">Updated by the catalog team.</p>
</section>

For Sercrod repetition, keep this distinction explicit:

item of items  -> item is each value
key in items   -> key is each key or index

Do not write item in items when the body expects item to be an item value.

Next: directives/for.md. For template-selected, non-destructive placement, read directives/iterate.md with directives/template.md.

P3: Server communication

Stable ID: server-communication

Use this pattern to make the request source and response destination visible in HTML instead of hiding them in an event callback.

• Read from: form selected by *keys.
• Write to: result selected by *response.
• Capability: HTTP POST handled by the communication runtime.
• Place in: the existing form and result paragraph.

<serc-rod data='{"form":{"name":""},"result":null}'>
  <label>
    Name
    <input *input="form.name">
  </label>

  <button
    type="button"
    *post="'/api/profile'"
    *keys="form"
    *response="'result'">
    Send
  </button>

  <p *if="result" *print="result.message"></p>
</serc-rod>

Next: directives/post.md, directives/keys.md, directives/response.md, and the network-contracts reference.

P4: Persistence

Stable ID: persistence

Use this pattern when the same HTML should save and restore declared data while the storage backend remains replaceable.

• Read from: draft selected by *keys.
• Write to: persistent storage under article-draft, then back to draft.
• Capability: save and load, implemented by the active file/storage path.
• Place in: the existing editor controls; storage produces no required UI.

<serc-rod data='{"draft":{"title":"","body":""}}'>
  <input *input="draft.title" placeholder="Title">
  <textarea *input="draft.body" placeholder="Body"></textarea>

  <button *save.store="'article-draft'" *keys="draft">
    Save locally
  </button>

  <button
    *load.store="'article-draft'"
    *keys="draft"
    *response="'draft'">
    Restore
  </button>
</serc-rod>

Next: directives/save.md, directives/load.md, and the filesystem adapter reference.

P5: Device capability

Stable ID: device-capability

Use this pattern to request a browser or device capability without naming a Capacitor plugin or browser API in application HTML.

• Read from: the camera selected by an explicit user action.
• Write to: photo through *response.
• Capability: camera, implemented by its role-mapped adapter.
• Place in: the existing preview image.

<serc-rod data='{"photo":null}'>
  <div class="existing-photo-panel">
    <img
      *if="photo"
      :src="photo.dataUrl"
      alt="Captured preview">
  </div>

  <button type="button" *camera.capture *response="'photo'">
    Take photo
  </button>
</serc-rod>

Next: directives/camera.md and the adapter reference. Permission timing and fallback behavior belong to the capability contract, not an invented generic rule.

P6: Document and existing-site composition

Stable ID: document-and-existing-site

Use this pattern to add managed content to a server-rendered, static, or documentation page without rebuilding the surrounding page as a component tree.

• Read from: the declared partial URL.
• Write to: imported content rendered by normal Sercrod rules.
• Capability: import/fetch of authored HTML.
• Place in: the existing <main> while header and footer remain outside it.

<header class="site-header">
  <a href="/">Existing site</a>
</header>

<serc-rod data='{"section":"account"}'>
  <main *import="`/partials/${section}.html`"></main>
</serc-rod>

<footer class="site-footer">
  Existing legal and navigation content remains here.
</footer>

Next: directives/import.md, directives/include.md, the Shadow DOM bridge, and the SSG/SSR reference.

P7: Lifecycle and external events

Stable ID: lifecycle-and-external-events

Use this pattern when values arrive after initial rendering through a named connection or platform event. Connection state and received data remain explicit.

• Read from: messages received from roomUrl.
• Write to: roomEvent through *response.
• Capability: WebSocket connection and observation.
• Place in: the existing status and message region.

<serc-rod
  data='{"roomUrl":"wss://example.com/rooms/demo","roomEvent":null}'
  *websocket="roomUrl"
  *response="'roomEvent'">

  <p>Status: <strong *print="$ws_ready ? 'connected' : 'disconnected'"></strong></p>

  <section *if="roomEvent">
    <p *print="roomEvent.message"></p>
  </section>
</serc-rod>

Next: directives/websocket.md. For remote notifications or diagnostic reporting, use the separate push workflow or diagnostics reference.

Pattern map

These patterns are reading routes, not exclusive application categories. A single page may use several patterns. When patterns meet, keep all four declarations visible and then consult the exact directive references.

Required reading after this file

1. Use ai-runtime-rules.md for execution boundaries and must-not rules.
2. Use ai-directives.md to locate the directive family and its status.
3. Read the exact directive reference and current dist/sercrod.js behavior.
4. Use completion before writing Sercrod syntax and the checker afterward.