sercrod

Sercrod AI Runtime Rules

This is the HTML-published copy of docs/spec/ai-runtime-rules.md. Use it with the current sercrod-current.zip, sercrod.js, and man.json.

For implementation-sensitive behavior, the current runtime remains the source of truth. If this page and sercrod.js disagree, inspect the runtime.

Sercrod AI 50KB Spec

This file is the common AI-facing Sercrod rule file for AI-assisted Sercrod work.

It is not a full manual. It is a compact rule file that prevents wrong assumptions before editing Sercrod-related code.

This file must explain both:

1. Source of truth

The current dist/sercrod.js is the source of truth for implemented behavior.

This file must not invent directives. This file must not treat planned behavior as implemented behavior. This file must not promote compatibility names as preferred names.

Status labels:

If behavior is unclear, write uncertain. Do not guess.

2. Sample policy

Examples in this file are conceptual. They are intentionally short. They are not the final syntax authority.

For exact syntax, check:

If a sample conflicts with dist/sercrod.js, dist/sercrod.js wins for implemented behavior. If exact behavior is still unclear, mark it as uncertain.

Do not invent samples. Do not rewrite working Sercrod samples into component-style JavaScript. Do not add Proxy, MutationObserver, watcher systems, virtual DOM, or component-style rendering to explain samples.

3. Core identity

Sercrod is HTML-first.

Sercrod directives are HTML attributes. Visible HTML structure is the primary structure. JavaScript supports the HTML structure, but must not replace it with a framework-style model.

Sercrod is an HTML-first runtime that carries explicit data and update paths through visible attributes.

Sercrod is not:

4. Different-category rule

Sercrod is not a variation of common JavaScript libraries.

Do not treat Sercrod as a familiar library with different names. The difference is categorical, not cosmetic.

This distinction is not an argument against existing frameworks. It is a result of Sercrod's design: the runtime starts from HTML attributes, Custom Elements lifecycle, and explicit update paths instead of a framework-style component state model.

AI must not:

If behavior is not defined here or in the current dist/sercrod.js, mark it as uncertain. Do not guess.

5. Proxy rule

Sercrod does not use JavaScript Proxy for change detection.

AI must not:

Sercrod writes values directly. The writing process already knows what it changed. Any later notification is notification, not detection.

6. MutationObserver rule

Sercrod does not depend on MutationObserver for change detection.

AI must not:

7. Adopted change-handling wording

Sercrod itself is the process that writes values and handles the resulting changes.

Sercrod does not have change handling as an added feature. It also does not have a feature for finding changes.

Sercrod does not use Proxy or MutationObserver for this update path because the runtime already owns the write path and can route the resulting update explicitly.

This is a result of Sercrod's design, not an intentional avoidance of existing technologies.

8. Runtime model in one map

Sercrod runtime is a direct flow.

HTML directive is read
expression is evaluated
data is read or written directly
render/update path is selected
parent, child, iterate, hook, and output paths are handled explicitly

The important point is:

Sercrod does not wait for something to notice that data changed.
The part that writes the value already knows it wrote the value.

This wording describes the runtime flow. It is not a claim that other web technologies are wrong for their own design goals.

Therefore:

write path can decide update path
update path can skip parent rerender
update path can still update children
child host can print changed data

Do not translate this into Proxy, watcher, observer, state store, or virtual DOM language.

9. Host lifecycle flow

A Sercrod host is a Custom Element.

Typical flow:

constructor prepares internal fields
connectedCallback waits until light DOM can be read
data attribute is parsed
templates are collected
parent host is resolved if present
child scope may be inherited or prepared
initial template is captured
stage data may be prepared
initial fetch may run
initial update runs
WebSocket may start after the initial render path

A disconnected host must clean up:

window key handlers
WebSocket connections
host-owned external handlers

10. Data and scope flow

The normal data scope is the nearest <serc-rod>.

Data flow:

host data is parsed from data attribute
if no own data exists, parent data may be inherited
if parent render passes child scope, child uses prepared scope
expressions read from current scope
assignments write to explicit targets

Directives read explicitly addressed data. Directives write only explicitly defined targets.

Parent-to-child data inheritance must follow current implementation. Child-to-parent data updates must follow current implementation.

If uncertain, mark it as uncertain.

11. Evaluation and assignment flow

Expression and assignment flow:

build evaluation scope
evaluate expression against scope
include event object for event expressions
resolve assignment target
write value directly to explicit data path
mark or schedule update according to caller path

Important:

expression evaluation reads values
assignment writes values
the update path is chosen by the caller
no watcher is needed to discover the assignment

12. Main update flow

Main update flow:

ignore nested update if already updating
require captured template
determine update reason
if host is dominated and update is automatic:
  avoid normal full rerender
  sync iterate regions where applicable
  rebuild internal lookup/index state
  finish
if host has *lazy and update is not forced:
  skip own full rerender
  update children path where applicable
  run updated hooks
  finalize
otherwise:
  clean up old window key handlers
  select display scope
  reset iterate regions for normal rerender
  render template
  rebuild lookup/index state
  run manual output, log, and updated hooks
  finalize
if update was dropped while busy:
  schedule one follow-up update

The key point:

parent full rerender is not the only update path
child update can still happen
iterate synchronization can still happen

Update path decision cheat sheet:

if the value was written by a Sercrod directive path:
  the writer already knows what it changed
  follow the update path selected by that caller
  do not add watcher, Proxy, or observer logic

if external project code mutates raw data directly:
  do not assume hidden change detection
  choose an explicit update path based on the target host

if a dominated parent only needs placement synchronization:
  prefer the non-forced automatic update path that lets *iterate sync add, remove, or move records
  do not force a full parent rerender by default

if only child hosts need refreshed output:
  use the child-update path already provided by the current implementation
  do not redraw the high-cost parent just to refresh child *print output

if the task is inside a project helper such as ssSrUpdate:
  treat the helper as project-level update policy
  prefer it where existing project code already uses it
  do not replace it with direct update() calls unless the task explicitly requires that

if tempted to call internal methods such as _updateChildren:
  remember they are internal only
  use them only inside the existing Sercrod or project integration path
  do not expose them as public API

Practical rule:

update(false) or a project wrapper around it is for ordinary non-forced synchronization
update(true) or forced update is for explicit redraw intent, not the default fix
child-update paths are for refreshing child hosts while preserving parent DOM
project helpers such as ssSrUpdate should preserve project-specific update rules

13. Parent and child Sercrod flow

A child <serc-rod> is its own Sercrod host.

When parent rendering reaches a child host:

parent sees child <serc-rod>
parent prepares child scope
if child has data expression:
  parent evaluates that data in parent scope
  child receives evaluated data
else if child has no own data:
  child may inherit parent scope
parent appends child host
child later performs its own update

The parent does not flatten the child. The parent does not render child internals as ordinary parent DOM.

Child update flow:

parent keeps track of child Sercrod hosts
parent may ask children to update
child uses its own render cycle
child evaluates its own directives
child prints inside itself

serc-rod versus ordinary element decision rule:

use child <serc-rod> when the child really needs its own Sercrod host:
  own data or evaluated child data
  own staged editing layer
  own template or shadow flow
  own event/update lifecycle
  own external bridge such as fetch, websocket, upload, or download
  independent child output that should update without parent full rerender

use an ordinary element such as div when the node is only structural:
  grouping
  layout
  show/hide or conditional wrapper
  slot or placement marker
  template candidate wrapper that does not need an independent host
  a place where parent scope must be prepared before any child lifecycle runs

Timing rule:

<serc-rod> is a Custom Element
connectedCallback can run as soon as the child host is connected
if parent code still needs to prepare child scope before the child starts, an unnecessary child <serc-rod> can run too early
in that case, use an ordinary element instead of a child <serc-rod>

Do not add a child <serc-rod> merely because a region is nested. A nested Sercrod host is a separate runtime unit, not a harmless wrapper.

14. Parent data change, lazy parent, and child *print

This behavior is critical.

A parent data change does not always mean parent full rerender.

Important flow:

a form control with *input receives input
Sercrod writes the new value to the explicit data target
if host is lazy or update path avoids parent full rerender:
  parent template may not be redrawn
  parent DOM can remain stable
  child Sercrod hosts may still be updated
  child host evaluates its own scope
  child *print writes updated text

Correct explanation:

parent data changed
parent full rerender was skipped
child update still ran
child *print reflected the changed value

Wrong explanation:

Proxy noticed the change
MutationObserver noticed the change
watcher detected the change
virtual DOM diff propagated the change

Do not write the wrong explanation.

15. Template render flow

Template render flow:

stored template is parsed
templates are collected
shadow templates are collected
top-level nodes are rendered
child Sercrod hosts are prepared, not flattened
after node scanning, iterate regions can be synchronized

Element render flow:

if node is child Sercrod:
  prepare child scope
  append child host
  do not render child internals as parent content
if node is *shadow template:
  register or skip as shadow declaration
clone element
collect directive flags
process template/include/import
process conditionals
process repetition
process input, attributes, events, fetch, upload, download, websocket, and output
process children when needed
append final element

16. Directive contract format

Use this compact format when documenting directives:

directive:
status:
group:
purpose:
flow:
reads:
writes:
rerender:
scope:
timing:
warn:
must_not:
sample_source:

If a field is unknown, write:

uncertain

Do not guess.

17. Conditional and branch control

Directives:

*if
*elseif
*else
*condition
*cond
*switch
*case
*case.break
*break
*default

Status:

implemented

Flow:

condition expression is evaluated
branch selection is decided
non-selected branch is not rendered or is skipped according to implementation
selected branch continues through normal render flow
switch/case selects matching branch
break-style behavior stops later branch matching where applicable

Reads:

condition expression
switch value
case value
current scope

Writes:

rendered branch selection

Must not:

do not replace with framework-style conditional rendering
do not invent hidden component state
do not treat *true and *false as independent core directives

*true and *false are helper attributes for condition-style flow. They are not independent core directives in the AI-facing list.

18. Repetition: *for

Directive:

*for

Status:

implemented

Flow:

evaluate list or object
create loop-local scope
repeat the element itself for each item
render each repeated element with its local scope

Dominated structural sync:

inside an automatic event path on a *dominate host, an existing element-level *for region may be synchronized without a full parent rerender
array object items are keyed by current item identity
existing records with the same key are preserved
missing records are removed
records whose order changed are moved
new keys create new records

Nested child hosts:

a child <serc-rod data="..."> inside a repeated item is an independent update world
that child data boundary does not stop the parent *for record from being moved or removed
if the parent item record remains, the child host and its local state are preserved
if the parent item record is removed, the whole record range is removed, including nested child hosts
data-bearing child hosts are safety boundaries for inherited child updates and staged preview propagation, not for parent *for item removal or movement

Use when:

the element itself is the repeated unit

Reads:

list data
item alias
optional index or local loop values if supported

Writes:

repeated element output

Must not:

do not confuse *for with *each
do not confuse *for with *iterate
do not force full rerender as the default answer to reorder problems

19. Repetition: *each

Directive:

*each

Status:

implemented

Flow:

evaluate list or object
keep the container element
repeat the container's child nodes for each item
render child nodes with loop-local scope

Use when:

the container should remain stable
only children should repeat

Reads:

list data
item alias
optional index or local loop values if supported

Writes:

repeated child-node output inside the kept container

Must not:

do not merge *each into *for
do not remove the container unless the implementation requires it
do not treat *each as non-destructive placement synchronization

20. Template and include flow

Directives:

*template
*include
*import

Status:

implemented

Flow for *template:

template directive gives a name
Sercrod resolves the name
Sercrod clones or stores the template as a reusable source
the template declaration is not rendered as ordinary output

Flow for *include:

include directive resolves a template name
Sercrod finds a registered template
template inner content is inserted into the current element flow
include depth is controlled to avoid runaway recursion

Flow for *import:

external or referenced template content is brought into render flow
exact source and timing must be checked against dist/sercrod.js and official samples

Must not:

do not replace with JavaScript component templates
do not hide visible HTML structure inside framework-style code
do not explain this as a virtual DOM template system

*template is important for *iterate.

21. Non-destructive placement: *iterate

Directive:

*iterate

Status:

implemented

Flow:

a template element declares or supports iterate behavior
Sercrod creates or uses a managed region
Sercrod does not treat it as a simple loop
after template scanning, Sercrod synchronizes iterate regions
the iterate expression resolves placement information
iterable is evaluated into an array-like sequence
variable defines the current item variable name
template is evaluated per item and selects a registered *template name
for each item:
  create local scope
  select registered template
  reuse existing record if possible
  render new template only when needed
  preserve child Sercrod instance when possible
  refresh child scope or data when needed
remove records no longer used
move existing nodes into the desired order
store the synchronized records

Meaning:

*iterate is placement synchronization
*iterate is not a simple loop
*iterate can preserve and reorder existing nodes
*iterate can preserve child Sercrod hosts while refreshing their scope

Important syntax note:

`*iterate="rows"` is the short form for `{ iterable: "rows", variable: "item", template: "item.type" }`. Object-style `*iterate`, such as `{ iterable: "rows", variable: "row", template: "row.kind" }`, is passed through Sercrod expression evaluation. It is not parsed as plain JSON. The `template` expression is evaluated for each item, and the result directly names a registered `*template`. Sercrod v0.2 does not use the older grouped-template warehouse shape `{ list, as, template, unit }`, and it does not use `*unit` or `*entry` for iterate placement.

Must not:

do not treat *iterate as just another name for *for
do not explain *iterate as a simple loop directive
do not ignore *template when explaining *iterate
do not solve reorder problems by forcing full parent rerender

22. Render control: *dominate

Directive:

*dominate

Status:

implemented

Flow:

host is checked for dominate-style render control
if update is automatic and host is dominated:
  avoid normal full rerender
  synchronize existing element-level *for regions where applicable
  synchronize iterate regions where applicable
  rebuild internal lookup/index state
  return
if update is explicit or forced:
  update may proceed according to specification

Meaning:

*dominate protects high-cost parent regions
*dominate avoids normal automatic rerendering
*dominate does not mean the region can never update
*dominate may still allow known structural add/remove/move synchronization for registered *for and *iterate regions

Official AI-facing name:

*dominate

Do not teach:

*dominant

Must not:

do not weaken *dominate by restoring normal automatic rerendering
do not force high-cost parent rerendering as the default solution

23. Local and global data helpers

Directives:

*let
*global

Status:

implemented

Flow:

expression is evaluated
local value or global-side value is prepared
later expressions can read the value according to scope rules
render flow continues with that value available

Meaning:

*let helps local expression flow
*global writes or exposes global-side data according to implementation

Must not:

do not explain these as a general framework store
do not invent hidden state management
do not use them to justify common-library assumptions

24. Literal and removal helpers

Directives:

*literal
*rem

Status:

implemented

Flow:

literal content is protected from normal expansion where applicable
removal helper removes Sercrod-only or non-output blocks where applicable
render flow skips or preserves content according to directive behavior

Must not:

do not treat removed blocks as runtime widgets
do not run Sercrod expansion inside literal content unless implementation says so

25. Input and timing

Directives:

*input
*lazy
*eager

Status:

implemented

Flow:

during render, current data may be written to the form control
input/change/composition events are bound as needed
when the user changes the field:
  value is normalized through input filters
  Sercrod writes value to explicit data target
  if stage is active:
    stage-inherited children may update
  else if eager:
    host update may be forced
  else:
    child update path may run while parent remains stable

*lazy flow:

host may skip its own full rerender
updated hooks may still run
child update path may still run
finalization still runs

*eager flow:

input can force host update immediately
parent template may rerender
children follow normal update/render structure

Must not:

do not explain input behavior as Proxy-based change detection
do not explain input behavior as watcher-based change detection
do not introduce hidden observers

26. Staged editing

Directives:

*stage
*apply
*restore

Status:

implemented

Flow:

if host has stage behavior:
  Sercrod creates or uses staged data
rendering can use staged data as display scope
input may write to staged data
apply commits staged data to real data
restore discards staged edits and restores from real data
stage-inherited children can update to preview staged values

Repeated child host rule:

If a child <serc-rod> appears inside a repeated scope, has no own data attribute, receives an internal current-item scope from the parent, and has empty *stage, the stage target should be the current repeated item, not the whole inherited parent scope, when that item is an object or array. Primitive repeated items such as strings, numbers, and booleans must not be treated as automatic merge targets unless the current dist/sercrod.js implements an explicit index write-back path. If this behavior is not implemented in the current source, mark it as planned or uncertain rather than treating it as implemented.

Meaning:

stage data is not ordinary committed host data
apply and restore control commitment

Must not:

do not treat staged data as ordinary direct host data
do not assume staged edits automatically mean committed edits
do not describe stage as a general state store

27. Save, load, keys, and destination

Directives:

*save
*save.file
*save.session
*save.store
*load
*load.file
*load.session
*load.store
*keys
*into

Status:

implemented

Flow:

source or action string is resolved
keys may select part of data
save writes selected data to the selected target
load retrieves data from selected source
into decides where loaded result is placed
after placement, update behavior follows Sercrod rules

Storage forms:

file
session
store

Must not:

do not turn storage into a general framework store
do not make storage semantics broader than the directive defines
do not describe this as an application database

28. Network and external bridges

Directives:

*post
*fetch
*api
*websocket
*websocket.send
*ws-send
*ws-to
*upload
*download
*keys
*params
*dry-run
*response
*into

Status:

implemented

Flow:

directive resolves request, action, endpoint, or bridge target
payload is prepared from current data or directive expression
supported communication directives may build a request envelope
external action runs
parsed response is mirrored to $response where implemented
result may be placed into Sercrod data only through the caller's defined placement path
after placement, update behavior follows Sercrod rules
cleanup runs when host is disconnected where needed

Current communication alignment:

*post sends a Sercrod JSON request envelope
*post uses *keys for outgoing top-level data selection
*api keeps body/payload as its request data source
non-GET JSON *api sends the Sercrod JSON request envelope
GET *api does not send *params or *dry-run markers in a JSON body
*upload sends FormData and appends Sercrod envelope fields where implemented
*params adds request metadata parameters only for directives that read it
*dry-run sends a marker only; the receiving API must honor it
$response is the unified parsed response mirror for post/api/upload response paths
*response is the preferred communication response placement directive
*response is the documented response placement directive for communication and adapter action results
*download is side-effect/event driven and must not be described as automatic data merge

Meaning:

Sercrod may bridge to external tools
Sercrod must not become the external system itself

Must not:

do not absorb external systems into Sercrod core
do not turn Sercrod into a full network framework
do not add external dependencies without explicit instruction
do not describe $upload or $download as the current response store for post/api/upload
do not treat *params or *dry-run as universal modifiers

28.5 Navigation adapter and page activation

Directives:

*page
*navigate

Status:

implemented

Runtime role:

Sercrod owns explicit target evaluation, page target collection, page visibility, and inserted partial rendering inside the host
the navigation adapter owns environment navigation such as browser Navigation API, history fallback, platform bridge, or project router handoff
adapter return values only signal handled or fallback

Flow:

*page evaluates to an explicit navigation target during render
initial activation uses current location when it matches a page target, otherwise the first page in DOM order
*navigate evaluates to an explicit target on click
Sercrod calls the active navigation adapter with host, element, source element, target, event, data, and scope
if the adapter returns false or is missing, the explicit Sercrod navigation request falls back/no-ops and normal event behavior is preserved
if the adapter handles the request, Sercrod prevents the click default and dispatches navigation events
matching *page activation hides inactive pages and shows the active page
same-origin URL-like HTML page targets may be fetched lazily as partial HTML on activation
inserted partial HTML is processed by the normal Sercrod render path
when available and enabled, matching page activation may wrap the visibility change and first partial insertion in document.startViewTransition()
View Transitions are progressive enhancement only; unsupported browsers, reduced motion, explicit opt-out, initial activation, and same-page activation use the normal path
lazy page partial fetches have no Sercrod timeout by default; positive navigation.page_timeout or pageTimeout config values add an AbortController timeout in milliseconds

Events:

sercrod-navigation-start
sercrod-navigated
sercrod-navigation-fallback
sercrod-navigation-error

Must not:

do not turn Sercrod into a router
do not add a route table, route params, nested route matching, or component-router state
do not globally intercept ordinary links
do not infer navigation targets from href, id, hashes, or CSS selectors
do not change *import behavior to explain Navigate Pager lazy loading
do not describe View Transitions as required, as a router feature, or as Sercrod owning animation semantics
do not describe page_timeout as global routing timeout, adapter timeout, or timeout for non-page directives
keep async work localized to the navigation loader or adapter boundary
do not spread await through the core render pipeline because page partial fetch is async
do not make every directive Promise-aware as a side effect of page partial fetch
this is not a rejection of asynchronous loading; it is a boundary rule
do not add Proxy, MutationObserver, watcher, or virtual DOM logic

29. Output and DOM writing

Directives:

*print
*compose
*textContent
*innerHTML

Status:

implemented

*print and *textContent flow:

read expression in current scope
normalize null, undefined, or false to empty output where applicable
apply text filter if applicable
write text to textContent
do not treat the result as HTML

*innerHTML and *compose flow:

read expression or composition source
write HTML-related output according to directive behavior
exact behavior should be checked against dist/sercrod.js and official samples

Important:

child *print runs inside child Sercrod update
child *print can reflect parent-provided or inherited data
child *print does not require parent full rerender

Must not:

do not silently convert text output into HTML output
do not use HTML-writing behavior when plain text output is intended

30. Attribute binding

Directives and patterns:

:class
:style
general :attribute
:value
:href
:src
:action
:formaction
:xlink:href
:id
:title
:alt

Status:

implemented pattern if present in current dist/sercrod.js

Flow:

scan attributes during element render
for each ':' attribute:
  evaluate expression
  if :class:
    static class attribute is the base class list
    string, array, or object may become dynamic class text
    final className is static class plus dynamic class
  if :style:
    value may become style cssText
  if :value and element is form-related:
    set value property too
  if URL-related:
    pass through URL filter
  otherwise:
    pass through attribute filter
  if value is false or null:
    remove target attribute
  cleanup directive attribute if configured

Meaning:

attribute binding writes attributes or properties during render
it is not a virtual DOM patch system

Must not:

do not promote uncertain *class or *style behavior
do not replace :class and :style with unrelated class systems
do not create a virtual DOM patch system

31. Event binding

Directive pattern:

@event

Examples:

@click
@submit
@input
@change
@focus
@blur
@keydown
@keyup
@keydown.window
@keyup.window

Status:

implemented pattern if present in current dist/sercrod.js

Flow:

during render, @event attributes are found
Sercrod registers event listeners
when event fires:
  event-aware scope is built
  event expression runs
  assignments write directly
  update behavior follows Sercrod event/update rules

Keyboard flow:

event name and modifiers are parsed
key names are normalized
modifier keys are checked
.window registers handler on window
handler executes in related host context
old window handlers are cleaned up before rerender or disconnect

Important:

event dispatch is event handling
event dispatch is not change detection

Must not:

do not treat event dispatch as change detection
do not infer Proxy-based behavior from event dispatch
do not invent arbitrary multi-key state tracking

32. Prevent helpers

Directives:

*prevent-default
*prevent

Status:

implemented

Flow:

during render, prevention directive is read
event behavior is modified according to directive mode
default browser behavior is prevented where specified

Meaning:

these are browser-event helpers
they do not create a custom event framework

33. Lifecycle, update, methods, logging, and manual output

Directives:

*updated
*update
*updated-propagate
*methods
*log
*man

Status:

implemented

Flow:

after update, updated hooks may run
ordinary element updated hooks may be absorbed into host context
manual output hooks may run after render
log hooks may run after render
explicit update can request an update path
methods may expose callable behavior according to implementation
finalization stores snapshots and clears update transaction state

Meaning:

updated hooks are post-update behavior
they do not discover changes

Must not:

do not treat internal functions as public APIs
do not expose internal methods unless explicitly requested
do not describe updated hooks as change detection

34. Shadow DOM bridge

Directives:

*shadow
*host
*shadow-host
n-host
n-shadow-host

Status:

implemented

Flow:

*shadow declares a Shadow DOM template
the *shadow declaration itself is not rendered as normal DOM
*host or *shadow-host on a real element requests connection
Sercrod attaches or uses a shadow root on the host element
Sercrod renders shadow template content into the shadow root
Light DOM children remain Light DOM
browser slot behavior remains browser behavior
host and template names are resolved explicitly or derived when supported

Meaning:

this is a bridge between visible HTML declarations and Shadow DOM
it is not a component framework replacement

Rules:

*shadow declares a Shadow DOM template
*host connects a normal element to a named *shadow template
*shadow-host is an alias of *host
n-host and n-shadow-host are namespace-style host aliases
n-shadow is not a required form

Must not:

do not replace this bridge with a framework component model
do not teach n-shadow as a required form

35. Flags, lookup, scheduling, and hooks

Internal flow:

directive-like attributes are collected as flags
after render, lookup/index state is rebuilt
later operations can find relevant nodes quickly
child Sercrod hosts can be tracked
write path can mark or schedule update
scheduling can coalesce update timing
finalize stores snapshots and clears transaction state

Meaning:

flags are an index of rendered directive-bearing nodes
scheduling manages timing
neither is change detection

Must not:

do not explain flag index as observer behavior
do not explain scheduling as watcher behavior

36. Alias policy

Do not list every n-* alias in normal guidance.

Rules:

explain official * names first
mention namespace-style n-* aliases may exist
list only aliases that matter for behavior or confusion
do not teach AI to prefer n-* names

n-* aliases:

status: alias
meaning: same as corresponding directive where implemented
preference: do not prefer over official * names

37. Items not to promote

Do not promote these as AI-facing core directives:

*dominant
*dynamic
*static
*class
*style
*unwrap
n-shadow

Use:

*dominate
:class
:style

38. Minimal examples

The examples below are conceptual and intentionally short. They are not the final syntax authority.

For exact syntax, check dist/sercrod.js, official directive reference pages, and working test pages.

38.1 Same host input and print

<serc-rod data='{"name":"Taro"}'>
  <input *input="name">
  <p *print="name"></p>
</serc-rod>

38.2 Element repetition

<serc-rod data='{"items":[{"name":"A"},{"name":"B"}]}'>
  <p *for="item in items" *print="item.name"></p>
</serc-rod>

38.3 Container repetition

<serc-rod data='{"items":[{"name":"A"},{"name":"B"}]}'>
  <ul *each="item in items">
    <li *print="item.name"></li>
  </ul>
</serc-rod>

38.4 Template and include

<serc-rod>
  <template *template="row">
    <p *print="item.name"></p>
  </template>

  <div *include="row"></div>
</serc-rod>

38.5 Event

<serc-rod data='{"count":0}'>
  <button @click="count = count + 1">Add</button>
  <span *print="count"></span>
</serc-rod>

38.6 Window key event

<serc-rod data='{"open":false}'>
  <input type="hidden" @keydown.window.escape="open = false">
</serc-rod>

If exact syntax differs in current dist/sercrod.js or official samples, follow those sources.

38. Detailed runtime flow supplement

This section is intentionally larger. It preserves the actual movement of Sercrod without including implementation code.

The goal is that AI can read the flow before touching source code.

38.1 Boot flow in more detail

Boot flow:

host object is created
internal fields are prepared
adapter registry is available
i18n and manual-data helpers may be prepared
light DOM is preserved long enough to read original declarations
data attribute is parsed
template declarations are collected before rendering destroys or moves them
shadow declarations are collected separately
parent Sercrod is resolved if the host is nested
child scope is prepared if parent already knows it
stage copy is prepared if the host is staged
initial fetch may run before normal render
initial update renders the host
post-render state is finalized

Key interpretation:

Sercrod must read visible HTML declarations before they are replaced.
Sercrod must preserve enough original structure to render again.
Sercrod must not guess later from already-rendered DOM when the source template is needed.

38.2 Data ownership flow

Data ownership is not a single global store.

Flow:

host may own its own data
child host may receive evaluated data from parent
child host may inherit parent scope when own data is absent
stage host may render from staged data
event expression may write to explicit host data path
storage or fetch may place loaded data into a specified destination

Interpretation:

nearest host is the normal execution unit
parent scope can feed child scope
child render remains child render
data can be shared by inheritance, but rendering is not flattened

AI must not:

replace this with app-wide state
replace this with observer state
replace this with component props/state terminology if it changes meaning

38.3 Expression flow

Expression flow:

current scope is selected
local loop variables may be added
stage scope may replace real data as display scope
event object may be added for event handlers
expression is evaluated
result is returned to the directive flow that requested it

Assignment flow:

left side is resolved
target owner is found
path is written directly
the caller decides whether update should be scheduled, forced, or limited

Important:

expression evaluation is not change detection
assignment is not discovered later
assignment is performed by the current action

38.4 Render node flow

Render node flow:

text node:
  placeholders are expanded
  resulting text is appended

comment node:
  comment is skipped or normalized according to implementation

element node:
  child Sercrod path is checked first
  shadow declaration path is checked
  shallow clone is created
  flags are collected
  structural directives are handled
  output directives may finish the element early
  child nodes are rendered if needed

Structural directives normally come before ordinary child rendering because they decide whether and how the element exists.

38.5 Same-element directive order

Same-element flow should be read like this:

the element is examined
directives on that element are classified
structural decisions are made
data-producing directives are evaluated
attribute and event bindings are prepared
content output may be written
children are rendered only if the directive flow allows it

Do not silently reorder behavior to imitate familiar frameworks.

If exact same-element order matters and is not confirmed, write:

uncertain

38.6 Conditional flow details

Conditional flow:

condition is evaluated in current scope
truthy or falsy result decides branch
branch may be rendered or skipped
elseif and else depend on prior branch state
switch evaluates a switch value
case compares against case value
case.break or break stops branch continuation where supported
default applies when no prior case matched

AI must preserve branch semantics. AI must not rewrite conditionals into hidden component logic.

38.7 Loop scope flow

Loop flow shared by *for and *each:

source list is evaluated
each item receives a local name
index-like local value may exist if implementation supports it
loop-local scope is layered over parent scope
each rendered output uses that loop-local scope

Difference:

*for changes the element itself into repeated outputs
*each keeps the container and repeats its child content

Do not collapse this difference.

38.8 Include and template lookup flow

Template lookup flow:

template name is resolved
current host template registry is checked
nearby or parent registry may be checked according to implementation
missing template causes warning or uncertain behavior
include inserts template content into current flow
template declarations themselves are not normal visible output

Why this matters:

*template is not a JavaScript component definition
*include is not a framework component mount
template HTML remains visible source material

38.9 Iterate placement flow in detail

*iterate flow should be read as a managed placement pipeline.

Pipeline:

template source is registered
iterate declaration creates a managed region
start and end markers define the region
region sync waits until templates are available
iterate expression resolves placement options
iterable provides the records to place
variable names the current item
template expression chooses the registered template name
existing item record is looked up
existing node is reused when possible
new node is rendered only when needed
existing node may be moved to new position
child Sercrod node may be kept alive
child scope may be refreshed
old records not used anymore are removed
unmanaged leftover nodes inside the region are cleaned

This is why *iterate is not *for.

Interpretation:

*for says: render this element for each item
*each says: keep this container and render its children for each item
*iterate says: synchronize this placement region with data and template candidates

With *dominate:

parent may avoid full rerender
iterate region can still be synchronized
existing nodes can be moved or refreshed
child Sercrod hosts can remain alive

This is a major Sercrod performance flow.

38.10 Dominate flow in detail

*dominate flow:

host receives update request
update reason is checked
if update is automatic and host is dominated:
  normal template redraw is skipped
  iterate regions can still be synchronized
  lookup/index state can be rebuilt
  update ends early
if update is explicit or forced:
  behavior follows explicit update rules

Mental model:

dominate protects the parent area
dominate does not freeze all data
dominate does not prevent all explicit updates
dominate avoids unnecessary automatic parent redraw

AI must not "fix" dominate by removing it. If output is stale, first ask which explicit update path or child update path should be used.

38.11 Input flow in detail

Input flow:

render writes current data value into form control when needed
input event is bound
composition behavior may be handled
user types or changes value
value is normalized
input filter may run
target expression is resolved
value is written directly
stage mode may redirect write into stage data
update strategy is chosen

Update strategy examples:

eager:
  force host update sooner

lazy:
  avoid parent full rerender when possible

ordinary:
  update according to default implementation path

child-output-sensitive:
  update children so child *print can reflect changed data

Important:

input is a writer
input is not a sensor
input does not need a watcher to know that it wrote

38.12 Child print flow in detail

Child print flow:

parent owns or provides data
child receives inherited or evaluated scope
child has its own template
child update is called
child evaluates *print expression in its current scope
child writes textContent

Case:

parent input changes parent data
parent lazy path skips parent full rerender
child update still receives current scope
child *print displays new value

Meaning:

the child can reflect data even when parent DOM is not redrawn

This is central Sercrod behavior.

Do not explain it as:

Proxy propagation
watcher propagation
MutationObserver propagation
virtual DOM reconciliation

38.13 Stage flow in detail

Stage flow:

stage host prepares staged copy
render may use staged copy as display data
input writes to staged copy
children inheriting stage can update against staged data
apply copies staged changes into real data
restore discards staged changes and rebuilds stage from real data

Interpretation:

stage is an editing layer
stage is not a framework store
apply is a commit operation
restore is a discard operation

38.14 Save and load flow in detail

Save/load flow:

directive resolves operation type
keys may select part of current data
save serializes selected data
target may be file, session, or store
load reads from source
loaded result is parsed or normalized
into decides destination
destination is written directly
update path follows the write

Interpretation:

save/load is browser-like persistence
it is not a database model
it is not global state management

38.15 Fetch, post, and API flow

Network flow:

request specification is resolved
method, URL, body, headers, or parameters may be prepared
current data may be used as payload
request runs
response is received
response is parsed according to directive behavior
result is placed into destination if specified
update path follows placement

Interpretation:

network directives are bridges
they are not a full data layer
they should not make Sercrod into a network framework

38.16 WebSocket flow

WebSocket flow:

host prepares websocket state
connection specification is resolved
connection opens after initial render path when applicable
incoming messages are handled
message data may be placed into Sercrod data
send directives or host methods can send data
disconnect cleanup closes or releases the connection

Interpretation:

WebSocket is an external bridge
it is not the Sercrod update mechanism itself

38.17 Upload and download flow

Upload flow:

upload directive resolves options
element becomes clickable if needed
hidden file input may be prepared
selected file is sent
response may be placed into data
update follows placement

Download flow:

download directive resolves options
request or source data is prepared
download action runs
file or response is delivered according to browser behavior

Interpretation:

upload/download are external bridges
they should not be generalized into a widget system

38.18 Attribute binding flow in detail

Attribute binding flow:

attribute name beginning with ':' is detected
target attribute name is resolved by removing ':'
expression is evaluated
special target handling is applied
value is filtered or normalized
target attribute or property is written
directive attribute may be removed from output

Special cases:

:class:
  string, array, or object may become class text

:style:
  style text may be written

:value:
  form value property may also be updated

URL attributes:
  URL filter may run

Interpretation:

attribute binding is direct output
it is not a patch tree

38.19 Event binding flow in detail

Event binding flow:

attribute beginning with @ is detected
event name is parsed
modifiers are parsed
listener is registered
when event fires:
  event-aware scope is prepared
  expression runs
  assignment writes directly
  update behavior follows event path

Window event flow:

.window modifier registers listener on window
host remains execution context
cleanup removes listener before rerender or disconnect

Keyboard event flow:

key token is normalized
modifier keys are checked
event matches only when key and modifiers match
unsupported arbitrary multi-key state must not be invented

Interpretation:

event is trigger
event is not detection of data change

38.20 Output flow in detail

Text output:

expression is evaluated
text value is normalized
text filter may run
textContent is written
children may not be processed further when text output owns content

HTML output:

HTML expression or composition source is evaluated
HTML-related output is written according to directive rules
safety behavior must follow implementation and samples

Interpretation:

*print is text
*innerHTML and *compose are not the same as *print
do not silently upgrade text to HTML

38.21 Shadow bridge flow in detail

Shadow flow:

shadow template is found
template name is resolved
template is registered
host element declares connection
shadow root is attached or reused
template content is rendered into shadow root
light DOM remains light DOM
slot distribution is browser behavior

Interpretation:

this is a DOM bridge
it is not a framework component rewrite

38.22 Manual, log, and updated flow

Post-update flow:

render or update completes
manual output hooks may run
log hooks may run
updated hooks run
child updated hooks may be absorbed according to implementation
ready state may be marked
snapshot or final state is stored
transaction flags are cleared

Interpretation:

updated hook is after update
it is not the mechanism that detects the update

38.23 Flag and lookup flow

Flag flow:

directive-bearing nodes are recognized
flags are collected
index is rebuilt after render
later operations can quickly find nodes by flag
child Sercrod hosts can be tracked

Interpretation:

flag index is lookup support
flag index is not observation
flag index is not change detection

38.24 Scheduling flow

Scheduling flow:

write path can request update
update may be scheduled instead of immediate
multiple requests may be coalesced
if update is already running, a follow-up update may be remembered
after current update finishes, follow-up can run

Interpretation:

scheduling controls timing
scheduling does not discover changes

38.25 How AI should debug Sercrod flow

When debugging, ask in this order:

1. Which host owns this data?
2. Is this parent host, child host, or staged data?
3. Which directive writes the value?
4. Does the write path force update, skip parent rerender, or update children?
5. Is *dominate preventing normal automatic parent rerender?
6. Is *iterate expected to synchronize placement instead of full redraw?
7. Is *print running inside parent host or child host?
8. Is exact syntax confirmed by official sample?
9. Is behavior implemented in current dist/sercrod.js?
10. If uncertain, mark uncertain instead of guessing.

Do not start with:

Where is the watcher?
Where is the Proxy?
Where is the virtual DOM?
Where is the state store?

Those are wrong starting points.

40. Remaining verification tasks

Before writing a fully detailed manual, verify these against dist/sercrod.js, official directive reference pages, and working test pages:

1. Exact *for syntax and alias behavior
2. Exact *each syntax and container behavior
3. Exact *iterate syntax and template relationship
4. Exact *dominate render-control behavior
5. Exact *template / *include / *import flow
6. Exact *input behavior with *lazy and *eager
7. Exact parent lazy input and child *print behavior
8. Exact *stage / *apply / *restore behavior
9. Exact save/load/file/session/store behavior
10. Exact *fetch URL plus *response placement behavior, including legacy compatibility
11. Exact *post / *api / *upload request envelopes, $response mirror, and *response placement
12. Exact *page / *navigate target evaluation, adapter fallback, browser navigation behavior, and lazy partial loading
13. Exact :attribute binding and URL filtering
14. Exact @event expression evaluation
15. Exact @keydown / @keyup key and modifier rules
16. Exact .window cleanup behavior
17. Exact *shadow / *host name matching
18. Exact warn messages and undefined value behavior
19. Exact behavior shown in https://sercrod.com/test/
20. Exact behavior shown in https://sercrod.com/test/example.html

41. AI must-not summary

AI must not:

42. Final AI decision rules

When uncertain:

  1. Preserve HTML structure.
  2. Prefer existing Sercrod directives over new JavaScript.
  3. Keep changes small.
  4. Mark unclear behavior as uncertain.
  5. Do not guess from common JavaScript library patterns.
  6. Do not expand Sercrod into a general framework.
  7. Do not make Sercrod larger than necessary.
  8. Check official samples before asserting exact syntax.
  9. Preserve parent-child Sercrod flow.
  10. Preserve *dominate and *iterate intent.