ts-core

name

ts-core

description

Authoring guide for the primary Native SDK app-logic path: 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 for new apps unless the user explicitly chose Zig, when writing or modifying a src/core.ts app core, fixing subset checker errors (NS1001-NS1069), 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, pinchMsg, dropMsg, appearanceMsg, chromeMsg, envMsgs, app manifest 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). Use ts-services alongside this guide for src/services work.

Author app cores in the TypeScript subset

TypeScript is the primary app-authoring language. An app core is a Native SDK app's deterministic logic: 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 starts as three files of truth and zero Zig: src/core.ts (this guide; plus core-class modules it imports under src/), src/app.native (the markup view over the core's model), and app.json (windows, identity, permissions). Existing app.zon manifests remain supported. Optional ordinary-TypeScript service modules live under src/services/ and are never imported by the core; load native skills get ts-services for that boundary. native init scaffolds the three-file base; 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.json/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). The rule-level deferrals carry class: "deferred" in the diagnostics catalogue — NS1011 (Map/Set), NS1019 (fixed arity), NS1040 (regexes), NS1042 (generators), NS1044 (BigInt/Symbol) — and their diagnostics say the capability is deliberately deferred, not impossible; the list below is the method-level remainder: .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), 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 or response line over its configured bound arrives cut, without a flag), and non-timer subscriptions (Sub.timer is the one subscription; one-shot needs are Cmd.delay, and process/fetch/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 v7):

• Cmd.none — no effects; returning a bare Model is sugar for [model, Cmd.none].
• Cmd.persist() — snapshot the just-committed Model through the engine-owned store. Requires "persist" in app.zon capabilities plus .persist = .{ .version, .restore = .{ .ok, .none, .err } }; the host owns canonical encoding, debounce/coalescing, atomic app-data placement, backup recovery, and replay.
• 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.
• Typed app services are the deliberate record-valued arm of this family: declare shared data shapes outside src/services/, import generated constructors from @native-sdk/services, and let those constructors encode requests and prove the typed success Msg arm. See native skills get ts-services. Raw Cmd.request remains bytes-oriented.

The named engine ops

These map directly onto the host's effect engine — files, HTTP, the clipboard, notifications, one-shot timers. Routed operations follow 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 a keyed 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; fire-and-forget writes and notifications have no routing arms. 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 bounds for routed operations stop the build (NS1030). Fire-and-forget operations fail closed under the host's validation instead.

• Cmd.store.set(key, bytes, { key?, ok, err }) / get / delete / scan / setMany — capability-gated, engine-owned per-record storage. Declare "store" in app.zon; keys are UTF-8 strings up to 512 bytes and values are bytes up to 1 MiB. setMany applies 1–64 entries atomically. get's ok bytes are [1][value...] for a hit and [0] for a miss, keeping an empty value distinct from absence. scan(prefix, { limit?, after? }, route) returns a little-endian length-prefixed page of key/value pairs plus an opaque next-key cursor; pass those next-key bytes back as after (a known literal cursor may be a string). The limit defaults to 100 and is capped at 256. Writes run off-loop in issue order, a synchronous read waits for earlier writes in the same command walk, every result journals, and failures route one of io_failed, over_bound, bad_key, rejected, or busy. The SQLite backing and app-data path are never part of the app-facing API.
• Checked relational SQLite: declare "sqlite" in app.zon. Add append-only, contiguous src/schema/NNNN_name.sql migrations (STRICT ordinary tables), commit the generated src/schema/migrations.lock.json, and add named statements in src/queries.sql: -- name: notesInFolder, -- name: moveNote :exec, or -- name: notesInFolder :live. native check applies the migrations and prepares every query with real SQLite, then generates flat Cmd.q<Name>(params, route) query constructors, typed Cmd.q<Name>(params) exec members composed only through Cmd.qTx([...], route), Sub.q<Name>(key, params, route) for :live, row/param interfaces, and decode<Name>Page. TEXT/BLOB rows are Uint8Array; parameters inferred from TEXT columns wrap bytes automatically; raw or uninferred dynamic TEXT (for example an FTS MATCH term) uses dbText(bytes). INTEGER is an exact number and generated decoders reject values outside ±(2^53−1). Live queries rerun after committed writes to their generated table dependency set, coalesced once per command frame. , , and own development migration operations. Do not edit or reuse a shipped migration number.

Model persistence is capability-gated. Without "persist", NS1028 warns that Cmd.persist() has no linked host binding; declaring the capability without issuing the command produces the inverse warning. Configure a monotonic schema version and three boot routes in app.zon: .persist = .{ .version = 1, .restore = .{ .ok = "restored", .none = "fresh_boot", .err = "restore_failed" } }. The ok/none routes name void Msg arms; err names a one-Uint8Array-field arm receiving corrupt, version_unknown, migrate_failed, io_failed, or rejected from boot restore or a later write. native check validates those route names and payloads, and native dev --core runs the same fence before starting its virtual host. Check stores the last accepted version/model-fingerprint pair under .native/cache and warns with NS1068 until a changed Model advances the version; runtime fingerprint checks remain the hard gate on cold checkouts. An older binary also refuses writes with version_unknown while a newer-schema snapshot is installed, preserving that snapshot across a rollback. A pure optional migrate(snapshot: Uint8Array, fromVersion: number): Model hook handles older versions (throw to fail). Version 1 snapshots the whole Model in a tagged, length-delimited engine format, so never put credentials in it. Cmd.readFile/writeFile are for user-visible files, exports, and blobs, not routine model storage.

The streaming ops: fetch, spawn, audio, and channels

Four 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.fetch({ url, method?, headers?, body?, timeoutMs?, maxLineBytes? }, { key?, line, ok, err }) — line-stream an HTTP(S) response. Each complete response line dispatches line as one Uint8Array field, so SSE and NDJSON parsers can update the Model incrementally. Exactly ONE terminal follows: a delivered, lossless response (non-2xx included) dispatches ok as one number field carrying the HTTP status; a cut/dropped line dispatches err: truncated, and transport failure, timeout, rejection, or cancellation dispatches err with that reason. maxLineBytes raises the 4 KiB per-line default up to 256 KiB for large event records; the per-line truncation flag is not exposed directly because any such loss makes the terminal loud. A duplicate live key is rejected rather than replaced so two responses cannot splice into one logical stream; Cmd.cancel(key) ends it loudly through err: cancelled.
• 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 's arm. Collected stdout over the bound routes with — a cut block never parses as whole.

The window verbs

The menu-bar lifecycle verbs are fire-and-forget, with no result Msg (the window's own frame event carries visibility 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.hideWindow(label) — order a live window out without closing it; native identity and views remain, and showWindow is the inverse.
• Cmd.setDockPresence(visible) — on macOS, switch between a regular Dock/app-switcher app and accessory/headless behavior; unsupported hosts ignore it.
• 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.

Launch at Login uses keyed routed effects: Cmd.launchAtLoginStatus({ key?, ok, err }) queries SMAppService.mainApp, and Cmd.setLaunchAtLogin(enabled, { key?, ok, err }) registers/unregisters it. The ok arm has one Uint8Array field containing UTF-8 enabled, disabled, requires_approval, or not_found; err carries unsupported, failed, or invalid_request. The result journals and replays exactly like Cmd.request. In app.zon, set initially_hidden = true on the startup window to prevent any launch flash, and allows_fullscreen = false on settings windows to retain resizing while disabling macOS native fullscreen.

Model-derived menu-bar status items

Export statusItem(model): StatusItemState from src/core.ts to make the generated launcher install a native menu-bar status item and keep its shell, presentation, and menu synchronized with committed model state. The three channels hash independently: changing icon/tooltip/activation hooks, title/width/tone/icon opacity/number style, or rows patches only that channel and never recreates the native item. statusItem is launcher-bound automatically, so do not repeat it in viewUnbound.

import { asciiBytes, utf8Bytes } from "@native-sdk/core";
import { type StatusItemState } from "@native-sdk/core/events";

export function statusItem(model: Model): StatusItemState {
  return {
    iconPath: asciiBytes("assets/menu-bar.svg"),
    tooltip: utf8Bytes("Player status"),
    activationCommand: asciiBytes("app.refresh"),
    alternateActivationCommand: asciiBytes("player.toggle"),
    openCommand: asciiBytes("app.refresh"),
    presentation: { title: model.playing ? utf8Bytes("MB PLAY") : utf8Bytes("MB"), width: 62, tone: "normal", iconOpacity: 1, monospaced: true, fontSize: 13, fontWeight: "semibold" },
    items: [
      { id: , : (), : (), : , : , : (), : , : (), : { : , : , : , : , :  } },
      { : , : (), : (), : , : , : (), : , : (), : { : , : , : , : , :  } },
      { : , : model. ? () : (), : (), : , : , : (), : , : (), : { : , : , : , : , :  } },
    ],
  };
}

The canonical records live in @native-sdk/core/events. Shell fields are iconPath, tooltip, activationCommand, alternateActivationCommand, and openCommand; all commands route through commandMsg(name): Msg | null. Presentation requires title, width (0 = host default), tone, iconOpacity, and monospaced; optional fontSize (omitted/0 = platform default) and fontWeight (omitted = regular; otherwise regular | medium | semibold | bold) add typography without breaking older cores. Use statusItems to compose several persistent menu-bar text/icon items with independent typography; attach the dropdown rows to whichever descriptor should open it. Actionable rows need unique non-zero whole u32 ids, and the runtime cap is 32 rows per item. Linux does not implement status items today.

For multiple items export statusItems(model): readonly StatusItemDescriptor[] instead (never both helpers). A descriptor has the singular fields plus stable non-zero id identity and live visible. Presence creates, absence removes, and changed icon/title/tooltip/visibility/activation/menu fields patch only that id; one menu update never recreates any native item. macOS supports eight simultaneous items. Row ids are scoped to one menu, so different status items may reuse them. This is the Vercel-shaped spend-indicator plus persistent-control-item surface.

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.

Model-declared secondary windows

Export windows(model): readonly WindowDescriptor[] to derive the secondary windows that should exist from committed model state. Import WindowDescriptor from @native-sdk/core/events, and construct entries with windowDescriptor from @native-sdk/core so omitted fields receive the canonical defaults. Presence is liveness: adding a descriptor creates the window, removing it closes the window and releases its retained view.

Each possible label has a statically compiled Native markup view at src/windows/<label>.native; for example descriptor label settings uses src/windows/settings.native. Spell that identity directly inside the canonical constructor as label: asciiBytes("settings"): window labels are static declarations, and native check/every build reject a dynamic label or one whose root file is missing. Window roots may import shared components nested under src/windows/ with the ordinary <import> syntax; the generated launcher embeds and hot-reloads the full import closure. The descriptor's canvasLabel must be unique across the whole app. Both the main view and every open window view rebuild from the same model after a Msg.

import { asciiBytes, windowDescriptor } from "@native-sdk/core";
import { type WindowDescriptor } from "@native-sdk/core/events";

export function windows(model: Model): readonly WindowDescriptor[] {
  if (!model.settingsOpen) return [];
  return [windowDescriptor({
    label: asciiBytes("settings"),
    canvasLabel: asciiBytes("settings-canvas"),
    title: asciiBytes("Settings"),
    width: 420,
    height: 240,
    restorePolicy: "center_on_primary",
    resizable: false,
    closePolicy: "quit",
    onCloseCommand: asciiBytes("app.settings-closed"),
  })];
}

closePolicy is "quit" by default. Under "quit", a user close really closes the window and routes onCloseCommand through commandMsg; map it to the Msg that clears the model's open flag. If the model keeps declaring the label, source wins and the next reconciliation recreates it. Under "hide", the same native window and view stay alive, no close command fires, and Cmd.showWindow("settings") reveals it. Stopping the declaration always performs a real reconcile close. The platform safeguards for hide are the same as manifest windows. Model-declared secondary windows are desktop-only.

restorePolicy accepts "clamp_to_visible_screen" (the default) or "center_on_primary". Model-declared windows do not restore persisted frames. On macOS, the latter centers a fresh descriptor with no x/y directly at native creation time; Windows and Linux currently keep their native default placement.

titlebar accepts "standard", "hidden_inset", "hidden_inset_tall", and "chromeless". The last removes all OS chrome and is required when a transparent model-declared window targets Windows; provide working app-drawn close/minimize controls for that fully skinned shape.

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.fetch's response lines, Cmd.spawn's stdout lines, Cmd.audioPlay's events, Cmd.channelOpen's posts, and audio capture chunks) are Cmd-INITIATED — imperative opens with a keyed lifecycle the app drives (Cmd.cancel for fetch/spawn, Cmd.audioStop for playback, Cmd.channelClose for external channels, and Cmd.audioCaptureStop for capture). 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, utf8Bytes, 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/ except src/services/ (subdirectories included). The whole core import graph still compiles as ONE native module - one flat namespace - and runs unchanged under node. src/services/ is a separate module class: importing it from the core, including with import type, is NS1065.

• 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/utf8Bytes 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/pinchMsg/dropMsg/appearanceMsg/chromeMsg/envMsgs), the model-derived launcher helpers (themeState/themePack/statusItem), and viewUnbound are DECLARED in core.ts and exported under their own names (export on the declaration or an un-renamed 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/chatbot (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 user-visible literals and templates into UTF-8 bytes with utf8Bytes. Use asciiBytes only where ASCII is part of the value's contract: command names, keys, paths, URLs, protocol tokens, and empty fields. The compiler recognizes both imports 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 imports run as plain functions with the same result:

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

const label = utf8Bytes(`${done} of ${total} done`); // arena UTF-8 bytes
const seed = utf8Bytes("Café…");                    // UTF-8 rodata
const command = asciiBytes("app.refresh");          // guaranteed ASCII

Arguments must be string literals or templates (the fold happens at compile time); dynamic text is already bytes, so there is nothing to bridge. utf8Bytes matches TextEncoder, including U+FFFD for lone surrogates. A non-ASCII literal/template passed to asciiBytes is NS1064, and the node implementation throws RangeError for a dynamic misuse. Hand-rolling either bridge gets no special treatment — its body observes code units and teaches NS1004.

The byte-text string methods