ts-core

name

ts-core

description

Authoring guide for TypeScript app cores - Model, Msg, update, and the pure functions they call, written in the closed app-core subset, checked by the @native-sdk/core frontend, and compiled ahead-of-time to native code by the external core compiler. Use when writing or modifying a src/core.ts app core, fixing subset checker errors (NS1001-NS1060), or deciding how to express state, messages, text (bytes and the byte-text string methods), text input, continuous controls (sliders, scroll), effects (Cmd), subscriptions (Sub), the host-event wiring channels (frameMsg, keyMsg, appearanceMsg, chromeMsg, envMsgs, app.zon assets), derived values, the view_unbound lint opt-out, local mutation of owned arrays, or how to split a core into modules under src/ (relative imports, namespace imports, @native-sdk/core/text, @native-sdk/core/events).

Author app cores in the TypeScript subset

An app core is the logic tier of a Native SDK app: Model (the app state), Msg (a discriminated union of everything that can happen), update(model, msg) (the one pure transition function), and the pure helpers they call. You write it as a TypeScript module rooted at src/core.ts - splitting into more modules under src/ when it grows (see "Splitting a core into modules") - and the build checks the whole import graph with the @native-sdk/core frontend and compiles it to native code with the external core compiler. No JS engine ships in the binary — the program either passes the subset checker and compiles to native, or you get a teaching error naming the rule, the fix, and the reason. The same file is executable TypeScript: it typechecks with stock tsc and runs unmodified under node, so you can poke behavior with plain node scripts before the native build.

A whole TS app is three files of truth and zero Zig: src/core.ts (this guide; plus any modules it imports under src/), src/app.native (the markup view over the core's model), and app.zon (windows, identity, permissions). native init scaffolds exactly that; the build detects src/core.ts in the tree (never a flag or config — a tree with both src/core.ts and src/main.zig is a teaching error) and generates the wiring outside the app. The loop:

native dev --core   # the fastest loop: run the core under node's virtual host —
                    # dispatch Msgs as JSON lines ({"kind":"add"}, {"$bytes":"…"}
                    # for bytes payloads, {"advance":1000} to run virtual timers),
                    # watch the model + effect transcript. Logic only, no renderer.
native dev          # build and run the real app (markup hot reload)
native check        # subset-check core.ts + validate markup + app.zon
native build        # ReleaseFast binary; native test runs the app's tests

The complete reference app in this idiom is examples/soundboard-ts in the SDK repo: the soundboard music library as three files and zero Zig — const catalog tables, REAL audio through the Cmd.audioPlay stream, scrub-to-seek on a markup slider, a motion-gated Sub.timer playback clock, the full text-edit engine on a search field, controlled scroll, registered cover assets, the width-adaptive grid through the frame channel, clipboard, and context menus, with an end-to-end suite driving the shipping markup.

The contract

export interface Model { /* readonly data fields only */ }

export type Msg =
  | { readonly kind: "add" }
  | { readonly kind: "toggle"; readonly id: number };
  // ...one arm per thing that can happen; at least two arms

export function initialModel(): Model { /* pure */ }

export function update(model: Model, msg: Msg): Model {
  switch (msg.kind) {
    // one case per arm; the switch must be exhaustive (no default needed
    // once every arm is present — a missing arm is a build error)
  }
}

• update is pure and synchronous: next model out, plus optionally command data describing effects. When a dispatch needs an effect, declare the return type Model | [Model, Cmd<Msg>] and return [nextModel, cmd] — the runtime interprets the command after the model commits and dispatches any result back to you as a Msg. initialModel may return the same pair ([Model, Cmd<Msg>]) to run a boot effect once at install, and an app that needs recurring timers exports subscriptions(model): Sub<Msg>. See "Effects are Cmd data" below.
• Exported helper functions (export function doneCount(model: Model): number) compile to public native functions — and every exported helper taking exactly ONE Model parameter also becomes a Model declaration markup binds by the helper's own name ({doneCount}), so derived values need no model field. One binding name per member: a helper that collides with a field (or another helper) is a taught NS1031.
• Update-only state (fields, helpers, or Msg kinds nothing in markup binds or dispatches — host-fired timer arms, persistence bookkeeping) is declared once: export const viewUnbound = ["nextId", "tick"] as const;. It emits as the view_unbound opt-out native check's unbound-state lint reads; a name outside the model surface is a taught NS1032. Entries are the TypeScript names exactly as declared ("nextId") and Msg kinds as their kind tags — the same names markup binds, because there are no other names.
• Names: your names are your names — fields, helpers, and locals emit into Zig with their TS spellings (doneToday stays doneToday), and markup binds them verbatim. String-literal unions emit as native enums.

The arena mental model

Everything update builds lives in a per-dispatch bump arena that is freed wholesale after the returned model is committed, so spreads, map, and filter are cheap by construction. At commit, only nodes your update actually created are copied into the persistent model heap — everything you spread through unchanged is shared with the previous model for free.

That is why the immutable style is not a performance tax: { ...model, tasks: model.tasks.map(...) } copies one small struct and one pointer array, never the world.

Both regions are the compiled core's own: the frame arena bounds one dispatch's transients, the model heap holds the committed model between dispatches, and the compiler's determinism fences keep every dispatch allocation-shaped and replayable.

What the subset means

The subset is TypeScript minus the ecosystem minus the purity violations — never minus basic syntax. Concretely: every basic statement, operator, and declaration form of the language compiles (every loop shape including do...while, labels with labeled break/continue, switch with default, the full assignment-operator family, ** and the shifts, const record destructuring, namespace imports over your own modules). What does not compile falls into exactly two families, each with a named teaching rule: the ECOSYSTEM the binary cannot carry (npm packages, Node/DOM APIs, regex/JSON/Promise/generator machinery, eval — no JS engine ships), and the constructs that would break a core's guarantees (purity and determinism, fixed shapes, one text representation, functions as declarations not values, static types with no runtime tags). Classes and exceptions are NOT in either family: data classes and throw/try/catch/finally compile (see below) — only their guarantee-breaking tails (inheritance, unsafe finally, untagged thrown values) teach. A construct that fails with a generic error instead of a teaching rule is a checker bug — the grammar matrix test (grammar_matrix.test.ts) pins every grammar production to its verdict so no silent gap can appear.

The banned families at a glance (each diagnostic names the fix and the reason at the site):

• No JS engine ships: eval, new Function, dynamic import(), debugger (NS1013); regexes (NS1040); BigInt/Symbol (NS1044); generators (NS1042); async/Promises (NS1002); npm imports (NS1035).
• Purity and determinism: mutation of SHARED data — parameters, model/msg trees, module tables, escaped locals (NS1001/NS1022/NS1051; your own function-local scratch arrays mutate freely, see "Local mutation" below), module-level let (NS1010), ambient time/randomness/IO (NS1005), effects outside the Cmd/Sub return paths (NS1017/NS1025).
• Fixed shapes and layouts: the class machinery beyond data classes — extends/super/abstract (NS1055), accessors/#-privates/class expressions/this-as-a-value (NS1056/NS1006), mutable statics (NS1010), generic classes (NS1053) — plus delete/getters/setters/computed keys (NS1012), for/in (NS1009), Map/Set (NS1011), runtime type/shape tests — typeof/in/instanceof/Object.* (NS1041). Data classes themselves compile — static methods, static readonly consts, and erased private/protected included (see "Data classes" below).
• One text representation: string indexing (NS1004), + concatenation and tagged templates (NS1018), string model fields (NS1024), the byte-text stays-out spellings — charCodeAt/normalize/replace and friends on bytes teach the byte-honest form (NS1060; the supported method surface is under "Text is bytes").
• Functions are declarations — or const local helpers: nested function declarations, non-const function values, ?.() (NS1046), and const helpers that capture/escape/under-annotate (NS1054 — the legal shape is below under "Local function values"); fixed arity — no defaults, rest, arguments, call spreads (NS1019); generics live on module-level declarations and monomorphize per call site (NS1050/NS1053).
• The mapping stays exact: var hoisting (NS1049), loose == (NS1048), comma/void/assignment-as-value outside a for-header (NS1043), array/parameter destructuring (NS1045), // (NS1047 — export lists and named value re-exports compile), namespace-alias-as-value and SDK namespace imports (NS1039).

What compiles (v1)

Model and message shapes:

• interface with readonly fields; nested interfaces; T | null for optional data.
• Model field types: number, boolean, string-literal unions ("all" | "active" | "done" → native enum), numeric-literal unions, Uint8Array (bytes), a nested interface, readonly Interface[] (arrays of object types), primitive arrays (readonly number[], readonly boolean[], arrays of literal-union tags), a tag-discriminated union ({ kind: "list" } | { kind: "detail"; note: Note } — arms may carry records, bytes, and primitive arrays), and T | null over any of these. Model unions compile to native tagged unions; switching arms in update retires the old arm's payload automatically at commit.
• Msg: a discriminated union on a readonly kind string tag, with primitive / bytes / interface payload fields. It must be a real union — give it at least two arms, or TypeScript collapses the alias to a plain object type and the checker rejects it.

Logic:

• switch on any union's kind tag — msg.kind (the Msg dispatch) and model-field unions (switch (model.view.kind)) alike — with member case labels, label stacking (case "a": case "b": body), break, and a trailing default covering the unnamed arms (without a default the switch must be exhaustive — NS1015; with every arm named the default is JS dead code and emits nothing) — and switch on a string-literal-union or numeric-literal-union value (switch (model.filter)) — an uncovered member skips the switch exactly like JS (a default anywhere but last is a taught stop in both forms) — and switch on a plain number or string value, lowered to an if/else chain with exact JS semantics: strict equality per case (NaN matches nothing, -0 matches 0, strings compare contents), cases tested in source order, default matching only after every case misses wherever it sits (an empty default: stacking onto the next body included); if/else; classic for (let i = 0; ...) including countdowns (i--, i -= k), multi-counter inits (let lo = 0, hi = n), and comma incrementors (lo++, hi-- — the for-header is the one home for comma sequences); do { ... } while (cond) (the body runs before the first test; continue jumps to the test, exactly node); for (const x of xs) over arrays and Uint8Array, with break/continue, plus the indexed pair form for (const [i, x] of xs.entries()) (exactly the [index, element] two-identifier binding — the index is the loop index, integer-classed; other tuple shapes stay taught); while; labeled statements on loops and blocks with labeled break/continue (outer: for (...) { ... continue outer; } — a labeled continue in a classic for still runs the incrementor, like JS); let locals with reassignment (and declared-then-assigned); ternaries; //; the empty statement .

Not yet in v1 — genuine roadmap deferrals, each stopping with a loud, tailored NS9001 naming the rewrite (never missing basic syntax; the banned-with-a-rule families live in "What the subset means" above): .toSorted()/.sort() without a comparator (JS ToString ordering; pass (a, b) => a - b), .reduce without an initial value (a taught NS1007 — JS throws on an empty array) or with an index parameter (use a classic loop), .indexOf/.includes on record arrays (match a field with .find/.findIndex), .join on number arrays (elements are float-valued; join byte values instead), float values (/, **, Math.round, Math.sqrt, float Math.floor-family results) where an integer is required such as an index (a taught NS1016 — those values can be fractional or NaN), Math methods beyond the batch above, Number methods beyond the three classifiers, float-valued template holes (JS float-to-string fidelity is a runtime v2 surface), arrays of unions (readonly View[]) or arrays of byte-strings (readonly Uint8Array[]) as model fields (wrap the element in a single-field interface), record payloads on Cmd.request results (results and errors arrive as one bytes payload; the record-shaped results are Cmd.fetch's { status, body } arm, Cmd.spawn's collect { code, output } arm, and the fixed audio event arm), streaming fetch responses (Cmd.fetch is buffered only; spawn line streams are the streaming surface), a collect spawn's stderr tail (v1 delivers the exit code and stdout; stderr is not surfaced — put diagnostics on stdout or check the code), per-line truncation flags (a stdout line over the engine's 4 KiB line bound arrives cut, without a flag), and non-timer subscriptions (Sub.timer is the one subscription; one-shot needs are Cmd.delay, and process/audio streams are Cmd-initiated, not subscribed).

Effects are Cmd data

update never performs an effect — it can return one, as inert data, alongside the next model. Import the factories from the SDK and declare the pair-return type:

import { Cmd } from "@native-sdk/core";

export function update(model: Model, msg: Msg): Model | [Model, Cmd<Msg>] {
  switch (msg.kind) {
    case "add":
      return [{ ...model, count: model.count + 1 }, Cmd.persist()];
    case "request_time":
      return [model, Cmd.now("tick")]; // dispatches { kind: "tick", at: <ms> }
    case "tick":
      return { ...model, lastTick: msg.at }; // bare model = [model, Cmd.none]
    case "ship":
      return [model, Cmd.batch([Cmd.persist(), Cmd.host("beep", model.count)])];
  }
}

The command set (Cmd wire format v3):

• Cmd.none — no effects; returning a bare Model is sugar for [model, Cmd.none].
• Cmd.persist() — ask the host to persist the committed model.
• Cmd.now("tick") — request a timestamp; the runtime dispatches the named Msg arm with the time (ms) as its payload. The target arm must carry exactly one number field ({ kind: "tick", at: number }), and tsc checks that for you.
• Cmd.host(name, ...args) — a fire-and-forget host command by literal name; the host decides what the name means. Args are numbers, OR exactly one bytes payload: a Uint8Array (Cmd.host("clipboard.write", model.draft)) or a flat inline record of number/boolean/Uint8Array fields (Cmd.host("cfg.save", { gain: model.gain, on: model.muted, label: asciiBytes("main") })) — the record lowers to one bytes payload from your types at build time, byte-identical under node and native. Anything else (a smuggled string, a nested record, a payload plus extra args) is a taught error (NS1020/NS1026).
• Cmd.request(name, payload, { key?, ok, err }) — a routed host command: the host performs name with the payload (same bytes/record rules) and dispatches exactly one result back to you as an ordinary Msg — the ok arm with the result bytes on success, or the err arm with the error bytes on failure. Both arms must carry exactly one Uint8Array field ({ kind: "loaded", body: Uint8Array }), checked by tsc and taught by NS1027. The routing is data — string-literal arm names, never callbacks — so the result decoder derives from your Msg types at build time. The optional key (a string literal) names the in-flight effect: issuing a request whose key is already in flight replaces it (the old result is dropped), which is the debounce/exactly-one-in-flight discipline.
• Cmd.cancel(key) — drop the in-flight keyed effect with that key, silently: a cancelled request, named engine op (readFile/writeFile/fetch/clipboardRead), or armed delay dispatches NEITHER arm — its result is simply dropped. The one exception is a live spawn stream (below): cancel ends the child and the stream's err arm dispatches with cancelled — killing a process is an observable event, kept loud on purpose.
• Cmd.batch([a, b]) — several commands from one dispatch, performed in order.

The named engine ops

These map directly onto the host's effect engine — files, HTTP, the clipboard, one-shot timers. Routing follows the Cmd.request rules (inline { key?, ok, err }, string-literal arm names, arm shapes checked by tsc and taught by NS1027), with one difference from request: each op's ok arm has the op's OWN result shape. Keys follow the one keyed-effect rule everywhere: issuing an op whose key is already in flight REPLACES the old one (the superseded op's result is dropped — no message), and Cmd.cancel(key) drops it silently. Every err arm carries exactly one Uint8Array field and receives a machine-readable reason. Paths, URLs, and bodies are bytes (asciiBytes for literals); dynamic values the engine refuses at runtime surface through the err arm, while compile-time-knowable bound violations stop the build (NS1030).

• Cmd.readFile(path, { key?, ok, err }) — read a whole file. ok arm: one Uint8Array field with the content. err reasons: not_found, io_failed, truncated (the file exceeds the engine's 1 MiB read bound — a cut file never passes as whole), rejected. Paths are at most 1024 bytes.
• Cmd.writeFile(path, bytes, { key?, ok, err }) — write a whole file (parent directories created, an existing file replaced whole; at most 1 MiB). ok arm: NO payload fields ({ kind: "wrote" }) — a successful write has nothing to report. err reasons: io_failed, rejected.
• Cmd.fetch({ url, method?, headers?, body?, timeoutMs? }, { key?, ok, err }) — a buffered HTTP(S) exchange. ok arm: exactly two fields, one number and one Uint8Array ({ kind: "fetched", status: number, body: Uint8Array }) — matched by type, so the names are yours. The status is the real HTTP status: a 404 is still ok (an HTTP-level error is a delivered response). err reasons: connect_failed, tls_failed, protocol_failed, timed_out, rejected, and truncated (the body exceeded the engine's 256 KiB buffered bound — never delivered silently cut). The spec is an inline object: url bytes (≤ 2 KiB), method one of "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" (default GET), headers an inline flat record — names are compile-time ASCII, values are string literals OR runtime bytes ({ authorization: bearerToken(model.apiKey), "content-type": "application/json" } — how a launch-supplied key rides an Authorization header; ≤ 8 headers, ≤ 1 KiB total, NS1029/NS1030), body bytes (≤ 64 KiB), timeoutMs a positive integer literal (engine default when omitted). Buffered only — no streaming responses in v1.
• Cmd.clipboardWrite(bytes) — put bytes on the system clipboard, fire-and-forget: there is no routing, and a refused or over-bound write is dropped by design.
• Cmd.clipboardRead({ key?, ok, err }) — read the clipboard. arm: one field with the text. reasons: (no clipboard service, over-bound content, pasteboard error), .

One honesty note on Cmd.persist(): it compiles and encodes, but no shipping host implements the persist verb yet, so the checker teaches NS1028 as a WARNING (never failing the build). Persist real state with Cmd.writeFile and load it back with Cmd.readFile from initialModel's boot command — the pattern every real app uses.

The streaming ops: spawn, audio, and channels

Three effect families deliver MANY results from one command — a keyed stream the app opens imperatively and drives (this is the opposite of Sub: a Sub is declared from the model and the host reconciles it; a stream is a Cmd with a lifecycle you cancel or stop). Routing still follows the Cmd.request rules: string-literal arm names, shapes checked by tsc and taught by NS1027.

• Cmd.spawn(argv, { key?, stdin?, line?, exit, err }) — run a subprocess, streaming stdout line by line. argv is an inline array literal of bytes elements ([asciiBytes("/bin/ps"), asciiBytes("-axo")], at most 16 elements, 2 KiB total; the array shape is NS1029, the bounds NS1030), and stdin (optional bytes, ≤ 4 KiB) is written to the child once. Each stdout line dispatches the line arm (one Uint8Array field) as it arrives, across dispatches; omit line to drop lines (an exit-only spawn, e.g. piping stdin to pbcopy). Exactly ONE terminal ends the stream: a clean exit dispatches the exit arm — one number field carrying the exit code (a non-zero code is still exit: the process ran; its failure code is yours to read) — and every other end dispatches err with the reason bytes: signaled, cancelled, rejected (a duplicate live key, or dynamic argv/stdin the engine refused), spawn_failed (the binary could not start). Lines over the engine's 4 KiB line bound arrive cut.
• Cmd.spawn(argv, { key?, stdin?, collect: true, exit, err }) — the same child, whole stdout buffered instead of streamed (the system-monitor shape: run ps, parse the block). No line arm (NS1027 teaches the conflict). The exit arm is a two-field record — one number field (the exit code) and one Uint8Array field (the collected stdout, up to 512 KiB), matched by type like Cmd.fetch's arm. Collected stdout over the bound routes err with truncated — a cut block never parses as whole.
• Cmd.cancel(key) aimed at a live spawn ends the child mid-stream; the stream's err arm dispatches with cancelled — loud on purpose, because killing a process is an observable event (the contrast with the named ops, whose cancel is silent). Spawn keys are the ONE exception to the replace rule: a spawn whose key is already streaming is rejected (err gets rejected), never replaced — a running subprocess is never killed implicitly; cancel it first.
• Cmd.audioPlay(key, { path?, url?, cachePath?, expectedBytes? }, { event }) — open the audio event stream. One player is the whole surface, so a new audioPlay always REPLACES the current playback (the one key-reuse exception besides ). The source cascade is the engine's: the local is tried first, a missing file falls through to (streamed progressively, cached at when given, integrity-gated by — omitted/0 means unknown size). At least one of / is required (NS1029); each is bytes, at most 1 KiB (NS1030). Prefer OMITTING for URL sources: when the app wiring configures a caches directory ('s ), the host derives the conventional content-addressed cache path from the URL itself — your update never builds filesystem paths, and replay re-derives the same path by construction. Pass only to override that convention.

The window verbs

The menu-bar lifecycle pair — fire-and-forget, no routing and no result Msg (the window's own frame event carries the resulting state):

• Cmd.showWindow(label) — un-hide + activate the window with the declared label (a string literal — window labels are declarations, in app.zon or a windows_fn descriptor): the counterpart to a close_policy = "hide" close and the tray "Open" consequence; also restores a minimized window. An unknown label is a no-op.
• Cmd.quitApp() — the graceful terminate, and the tray "Quit" consequence: the host quits through the SAME shutdown path a last-window close takes, so the stop hook runs exactly once and a recording session seals its journal.

Commands are constructed inline in the return path and nowhere else (NS1017): never in the Model or a Msg, never in a local, never in a helper. This is what keeps effects inside the dispatch cycle and replay honest.

The init command

initialModel may return the same pair to run a boot effect once at install, before the first view build — loading a store is the canonical use:

export function initialModel(): [Model, Cmd<Msg>] {
  return [
    { notes: [], loading: true },
    Cmd.request("store.read", asciiBytes("notes.bin"), { key: "boot", ok: "loaded", err: "load_failed" }),
  ];
}

A plain initialModel(): Model stays exactly as before; the pair is opt-in.

Subscriptions are Sub data

Recurring effects are declared, not issued: export subscriptions(model): Sub<Msg> and return descriptors derived from the current model. After every commit the host reconciles the returned set against its active timers by key — a new key (or a changed interval) arms a timer, a missing key cancels it — so starting, stopping, and re-tuning timers is just returning different data:

import { Sub } from "@native-sdk/core";

export function subscriptions(model: Model): Sub<Msg> {
  if (!model.running) return Sub.none;
  return Sub.batch([
    Sub.timer("tick", model.fast ? 250 : 1000, "tick"), // dispatches { kind: "tick", at: <ms> } every interval
    Sub.timer("autosave", 30000, "save_now"),
  ]);
}

• Sub.none — no subscriptions (everything paused).
• Sub.timer(key, everyMs, "tick") — a repeating timer named by its string-literal key; each fire dispatches the named arm with the current time (ms) as its single number payload (the same arm shape Cmd.now targets). The interval may derive from the model.
• Sub.batch([...]) — several at once.

Sub values follow the Cmd purity rule with their own home (NS1025): built inline in subscriptions' return path, never stored, never returned from anywhere else. Debounced re-arm falls out of reconciliation — change the key or interval and the timer re-arms; drop it from the set and it stops.

Keep the Sub-vs-stream line straight: a Sub is DECLARATIVE — derived from the model, started and stopped by reconciliation, and the app never opens or closes one. The multi-result streams (Cmd.spawn's lines, Cmd.audioPlay's events) are Cmd-INITIATED — imperative opens with a keyed lifecycle the app drives (Cmd.cancel for spawn, Cmd.audioStop for audio). If the effect should exist exactly while some model state holds, it wants a Sub shape; if the app decides when it starts and ends, it is a stream.

One caveat for node-side pokes: the build resolves the @native-sdk/core* specifiers for you, but plain node does not know them, so quick behavioral checks under node work directly on cores with no SDK import, and on cores importing Cmd, Sub, asciiBytes, or the text engine only with a module mapping (or by copying the SDK module files next to the core and rewriting the specifiers). native dev --core already maps them.

Splitting a core into modules

src/core.ts is the ENTRY module; a core that outgrows it splits into more .ts files under src/ (subdirectories included). The whole import graph still compiles as ONE native module - one flat namespace - and runs unchanged under node.

• Spell relative imports with the real filename: import { parsePs } from "./parsers.ts" (node's loader resolves real files, not bare stems - a missing extension or a missing file is a taught NS1037).
• src/ is the boundary: ../ escapes and absolute paths are taught (NS1034); bare npm specifiers are taught (NS1035 - vendor the code under src/ or make the import import type). Only @native-sdk/core (the intrinsic Cmd/Sub/asciiBytes surface) and the SDK library modules below carry runtime meaning from outside.
• Everything module-level is importable: interfaces, literal-union aliases, discriminated unions, module const numbers and tables, and helper functions all cross files (renamed imports and import * as ns namespace aliases both work — the alias is dot-syntax over the same flat namespace, never a value of its own). Export lists and value re-exports work too: export { helper, doneCount as remaining } binds names over existing declarations, and export { parsePs } from "./parsers.ts" forwards another module's export by name (a renamed binding emits as a flat-namespace alias). Type names and EXPORTED value names must be unique across the core's files (NS1038 - declare once, import where used; renamed exports claim their new names in the same namespace); colliding PRIVATE helpers are fine (the compile uniques them per module).
• No runtime import cycles (NS1036). import type back-edges are legal and idiomatic: a helper module type-imports Model from ./core.ts while core.ts runtime-imports the helpers - that is the expected shape, not a smell.
• The entry contract (NS1014): update, initialModel, subscriptions, the wiring channels (commandMsg/keyMsg/frameMsg/appearanceMsg/chromeMsg/envMsgs), and viewUnbound are DECLARED in core.ts and exported under their own names (export on the declaration or an un-renamed export { update } list entry — a rename or a re-export from an imported module cannot bind an entry point) - imports may FEED them, never replace them. The markup binding surface is also entry-only: an exported single-Model-parameter helper binds () only when it is DECLARED in — export lists participate under their exported names ( binds ), but a re-export of an imported helper does not bind (under node the app's module object is the entry's exports, so it would bind natively but not exist under node). Imported modules export cross-module API for update and the entry helpers to call.

The reference splits are examples/soundboard-ts (core.ts + library.ts + player.ts + the SDK text engine), examples/system-monitor-ts (core.ts + parsers.ts + table.ts + the SDK text engine), and examples/ai-chat-ts (core.ts + api.ts — the JSON-over-bytes wire-format reference: request encoding and a targeted parse walk that returns null on anything malformed) in the SDK repo.

Text is bytes

string in a core is for literals, string-literal-union tags, and === comparisons — content equality, on tags and plain string values alike (name === "app.add" in a command mapper works and behaves identically under node and native). Dynamic, user-visible text lives in the Model as Uint8Array — indexing yields byte values, .length is byte length, subarray is a view and slice is a copy, and both resolve their bounds the JS way (negatives count from the end, out-of-range clamps, a crossed range is empty), identical under node and native. Observing a string's code units (.length, s[i], .charCodeAt) is banned (NS1004) because UTF-16 and UTF-8 would disagree, and + concatenation is banned (NS1018) because runtime string building needs a JS string heap the binary does not carry — build text with template literals into bytes instead.

Turn literals and templates into bytes with the asciiBytes intrinsic from the SDK. The compiler recognizes the import by identity and folds every call at compile time — a literal argument becomes rodata, a template becomes per-dispatch arena bytes — and under node the same import runs as a plain function with the same result:

import { asciiBytes } from "@native-sdk/core";
export type Bytes = Uint8Array;

const label = asciiBytes(`${done} of ${total} done`); // arena bytes
const seed = asciiBytes("Stretch");                   // rodata, free to commit

Arguments must be string literals or templates (the fold happens at compile time); dynamic text is already bytes, so there is nothing to bridge. Hand-rolling the old bridge shape (function asciiBytes(s: string): Bytes { ... }) no longer gets special treatment — its body observes code units and teaches NS1004.

The byte-text string methods

Bytes read like text: the everyday string methods work directly on Uint8Array values, with byte-honest semantics — every length, offset, and index is a BYTE length/offset (never a character count: é measures 2 and padStart pads by bytes), search is byte-wise, and case mapping is Unicode SIMPLE case mapping (code point → code point from the Unicode tables; locale-free, no special casing — ß stays ß, σ uppercases to Σ; bytes that are not well-formed UTF-8 pass through case mapping unchanged). Natively each call lowers onto the compiled core's runtime; under node the devhost installs the same methods from the same Unicode tables, so both runtimes produce identical bytes.

const query = model.query.trim().toLowerCase();          // JS whitespace set; simple case map
if (title.toLowerCase().includes(query)) { ... }         // byte substring search
const bar = asciiBytes("#").repeat(used).padEnd(w, asciiBytes("."));  // w is a BYTE width
const cells = row.split(asciiBytes(","));                // Uint8Array[] — the array is yours (push works)
const ext = name.lastIndexOf(asciiBytes("."));           // byte offset, -1 when absent
const last = line.at(-1) ?? 0;                           // byte value | undefined (the .find one-empty)

• toUpperCase() / toLowerCase() — fresh bytes, simple case mapping only (locale casing stays out; toLocaleUpperCase teaches NS1005).
• repeat(n) — repeat(0) is empty; the count is an integer position (a fractional flow is NS1016), and a NEGATIVE literal stops the build — JS throws RangeError there, so a dynamic negative count is the same crash on both runtimes (node throws, native panics): guard n >= 0 first.
• startsWith(b) / endsWith(b) — bytes needles; the empty needle is true, exactly String's.
• includes(x) / indexOf(x) / lastIndexOf(x) — dispatch by argument type: a BYTES argument is substring search with String's shapes (indexOf(empty) is 0, lastIndexOf(empty) is the byte length, offsets are byte offsets), a NUMBER argument keeps the TypedArray element search node already ships (one byte value, SameValueZero — includes(66.5) is false, -0 matches 0); no fromIndex/position arguments in v1.
• padStart(n, fill?) / padEnd(n, fill?) — n is the target BYTE length, default fill " "; the last fill repetition truncates BY BYTES (a multi-byte fill can cut mid-sequence — identically on both runtimes); at-or-under target returns the receiver unchanged.
• trim() / trimStart() / trimEnd() — strip the JS whitespace set (tab/LF/CR family, NBSP, the Unicode spaces, U+FEFF) decoded over UTF-8; views, no copy. Invalid UTF-8 is not whitespace — trimming stops there.
• split(sep) — bytes separator, Uint8Array[] out with String.split's shapes (leading/trailing/adjacent separators produce empty elements; no match is [whole]); elements are views, the ARRAY is locally owned (push/sort it before it escapes); an empty separator literal is a taught stop (per-code-point splitting would expose the encoding seam), and no limit argument in v1.
• at(i) — byte access: the byte value at a byte index (negatives from the end) or undefined out of range — fold with ?? or test === undefined.

The stays-out tail teaches by name (NS1060 unless noted): charCodeAt/charAt/codePointAt read UTF-16 code units bytes do not have (read b[i]/.at(i), slice byte ranges), normalize is a host-edge concern, replace/replaceAll are named deferrals (rebuild with split/indexOf + a push-builder of parts), localeCompare/toLocaleUpperCase/toLocaleLowerCase read the ambient locale (NS1005), and match/matchAll/search take regexes (NS1040).

The SDK text helpers remain for what the methods do not cover: containsIgnoreCase (ASCII case-insensitive search) and orderIgnoreCase (an ASCII case-insensitive .toSorted comparator) from @native-sdk/core/text. trimAsciiSpaces also stays, but it is NOT .trim(): it strips space/tab/CR only — never LF — as a no-copy view, which is exactly right for line-oriented parsers where \n is the record separator; for user input and general whitespace, .trim() is now the canonical form.

A freshly created Uint8Array is writable until it escapes (stored, returned, passed on); after that it is immutable like everything else. One consequence worth knowing before you build byte output: a buffer PASSED to a helper has escaped, so a writing helper cannot take an out-parameter — build bytes with measure-then-fill inside one function (count the output length, allocate exactly it, write inline), or build a Uint8Array[] push-builder of parts and concatenate once (examples/ai-chat-ts/src/api.ts does both, JSON escaping included). === on two Uint8Array values is banned (it would be JS reference identity, which has no native mapping) — compare an id field, or contents with a loop (s.startsWith(t) && s.length === t.length is the whole-equality idiom). bytes.join("-") renders byte values as decimal text with a literal separator (arena bytes, same result under node); number arrays have no .join because their elements are float-valued.

Text input from markup

A markup text control (<text-field text="{draft}" on-input="draft_edit" />) needs two things from the core: a bytes field the control renders (draft), and a Msg arm carrying the text-input event. The event union mirrors the runtime's event vocabulary structurally (markup's on-input matches the shape and translates each runtime event into your union at dispatch). Import it — import { type TextInputEvent } from "@native-sdk/core/text" (also re-exported by @native-sdk/core/events) — or copy this declaration verbatim into the core:

export type TextCaretDirection = "previous" | "next" | "previous_word" | "next_word" | "start" | "end";
export interface TextCaretMove { readonly direction: TextCaretDirection; readonly extend: boolean; }
export interface TextSelection { readonly anchor: number; readonly focus: number; }
export type TextInputEvent =
  | { readonly kind: "insert_text"; readonly text: Uint8Array }
  | { readonly kind: "delete_backward" }
  | { readonly kind: "delete_forward" }
  | { readonly kind: "delete_word_backward" }
  | { readonly kind: "delete_word_forward" }
  | { readonly kind: "clear" }
  | { readonly kind: "move_caret";  :  }
  | {  : ;  :  }
  | {  : ;  : ;  :  |  }
  | {  :  }
  | {  :  };

   =  | {  : ;  :  };

Your update reduces the events over the draft bytes. A minimal reducer (append / backspace / clear, caret events ignored) covers simple fields; full caret/selection/composition fidelity is ONE IMPORT — the SDK ships the complete byte-splice engine as @native-sdk/core/text (applyTextInputEvent + clampedInsertEvent; see "Splitting a core into modules"), so no core hand-rolls it anymore. Stacked case labels share a body (case "move_caret": case "set_selection": return draft;) as long as the shared body reads no payload.

Continuous controls from markup

Sliders and scroll regions stay model-driven (a committed model has no sync hook): bind the widget's value and receive the applied value back as a Msg.

• Slider (on-change, the value-payload change event): a slider's on-change with a bare tag naming a ONE-NUMBER FLOAT arm dispatches the applied 0..1 fraction into it (<slider value="{progressFraction}" on-change="scrubbed" label="Seek" /> with { kind: "scrubbed"; fraction: number } — the fraction must be float-classed; an integer arm is refused because the value is a clamped fraction). A VOID arm keeps the older static form ("something changed", no value). The same one-number float arm carries a split's on-resize fraction.
• Scroll (on-scroll, the ScrollState mirror): name an arm carrying the scroll-state record — matched by field name, the TextInputEvent rule. Import the record (or declare the same shape in-file). Echo offset into a model field bound as the scroll's value, and setting that field in update scrolls the region (page changes reset to top):

import { type ScrollState } from "@native-sdk/core/events";
// (or declare it yourself: { offset, velocity, viewportExtent, contentExtent }, all numbers)
export type Msg = /* ... */ | { readonly kind: "library_scrolled"; readonly scroll: ScrollState };

<scroll value="{libraryScrollTop}" on-scroll="library_scrolled"> ... </scroll>

The host-event wiring channels

The generated wiring detects each channel from an export (export exists → wired; a wrong shape is a taught NS1033). Event records are matched by field name, STRUCTURALLY: import them from @native-sdk/core/events (FrameEvent, KeyEvent, ColorScheme, ChromeInsets/ChromeButtons) or declare the same shapes in your core — both emit as your module's types and match identically. The appearanceMsg/chromeMsg arms themselves stay inline union members (kind plus the event's fields — the subset has no intersection arms); the SDK's AppearanceEvent/ChromeEvent records are those arms' canonical payload shapes, importable for helper signatures.

• commandMsg(name: string): Msg | null — menus, shortcuts, and chrome tabs, by command id (string equality works on string values).
• frameMsg(model: Model, frame: FrameEvent): Msg | null — presented frames. FrameEvent is exactly { width, height, timestampMs, intervalMs } numbers (canvas points; fractional milliseconds). Return null for frames that change nothing — the idle law holds exactly when an idle app dispatches nothing (a frame arm that always returns a Msg would spin the loop at full frame rate). The installing frame is excluded; the first PRESENTED frame corrects any seeded value.
• keyMsg(key: KeyEvent): Msg | null — the app-level key FALLBACK (a focused widget's own keys and editable text always win first). KeyEvent is exactly { key: string; shift: boolean; control: boolean; alt: boolean; super: boolean }; the key NAME arrives lowercased (key.key === "space").
• export const appearanceMsg = "<arm>" — system appearance changes dispatch the named arm, a record of exactly { colorScheme: ColorScheme; reduceMotion: boolean; highContrast: boolean } where ColorScheme is a NAMED "light" | "dark" alias (routing is data: a string-literal arm name, the effects rule applied to the app shell).
• export const chromeMsg = "<arm>" — window-chrome geometry (the hidden-titlebar channel), a record of exactly { insets: { top; right; bottom; left }; buttons: { x; y; width; height }; tabsProjected: boolean } (numbers/boolean). Delivered before the first view build and again on changes.
• export const envMsgs = [{ env: "NAME", msg: "<arm>" }] as const — each named environment variable present at launch dispatches its value through the arm (exactly one Uint8Array field, BytesKind — annotate with readonly EnvMsg<Msg>[] from the SDK for tsc checking) as one journaled Msg right after the boot command. The core never reads the environment (NS1005), and neither does replay: the deliveries are journaled at record time and fed back from the journal, so a recording replays byte-identically even when the variables are unset or changed at replay launch.
• app.zon .assets.images — .assets = .{ .images = .{ .{ .id = 1, .path = "assets/art/cover.jpg" }, ... } }: each file is read once at launch and registered on the installing frame; the is the markup avatar bindings reference (), and a missing file or failed decode keeps the initials fallback.

The rules the checker enforces

Every diagnostic carries one of these IDs plus the fix and the why. Write to them up front:

• NS1001 shared data is immutable; your own scratch is yours. Never mutate model, msg, parameters, module tables, or anything reached from them — build the next value ({ ...model, tasks: [...model.tasks, task] }) or copy first (const copy = xs.slice()). Arrays this function creates itself mutate freely until they escape — appends via xs[xs.length] = v, all-owning reassigned bindings, and readonly-reader borrows included (see "Local mutation" above). The previous model stays live for rendering and undo; unchanged parts are shared, not copied.
• NS1002 updates are synchronous. No async/await/Promises in a core. Work that takes time is command data; the runtime dispatches your Msg with the result.
• NS1003 models hold data, not functions. No function-typed fields in the Model/Msg tree. Name the behavior as a message and handle it in update.
• NS1004 text is not indexable. No .length/s[i]/.charCodeAt on string. Bytes: Uint8Array; literals and templates become bytes through the asciiBytes intrinsic.
• NS1005 update is deterministic. No Date.now(), Math.random(), or ambient IO. Take time and randomness as message payloads.
• NS1006 classes are data classes, declared at module level. class with annotated fields, one constructor, and plain methods compiles (see "Data classes" above); class expressions, this outside a member body, and new of anything but a data class (or Uint8Array) are taught.
• NS1007 implicit builtin throws stay out. A JS builtin that throws mid-operation (.reduce with no initial value on a possibly-empty array) is taught toward its explicit form; your own throw of a subset value is supported control flow (see "Exceptions" above).
• NS1008 only erasable syntax. No enum, namespace, decorators, parameter properties. String-literal unions are the enum.
• NS1009 no for/in. Fixed shapes, no prototypes; model the data as an array and walk it with a classic loop.