Add compiled typography and model theme overrides

apps/schema/public/app/v1.json

@@ -213,6 +213,19 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "fonts": {
+          "type": "array",
+          "maxItems": 8,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "path"],
+            "properties": {
+              "id": { "type": "integer", "minimum": 64, "maximum": 9007199254740991 },
+              "path": { "type": "string", "pattern": "^assets/", "minLength": 8 }
+            }
+          }
+        },
         "images": {
           "type": "array",
           "items": {

build.zig

@@ -1143,6 +1143,26 @@ pub fn build(b: *std.Build) void {
         ts_core_e2e_step.dependOn(&status_driver_run.step);
         test_step.dependOn(&status_driver_run.step);
 
+        const typography_reference_run = managedExampleRun(b, host_cli_exe, &.{ "test", "-Dplatform=null" });
+        typography_reference_run.setCwd(b.path("examples/typography"));
+        typography_reference_run.has_side_effects = true;
+        typography_reference_run.setEnvironmentVariable("NATIVE_SDK_TEST_VIEW_BACKEND", "zig");
+        typography_reference_run.setEnvironmentVariable("NATIVE_SDK_TEST_VIEW_REFERENCE", b.pathFromRoot(".zig-cache/typography-view-reference"));
+        _ = typography_reference_run.captureStdOut(.{});
+        _ = typography_reference_run.captureStdErr(.{});
+        const typography_driver_run = managedExampleRun(b, host_cli_exe, &.{ "test", "-Dplatform=null", "-Dtypescript-view=true" });
+        typography_driver_run.setCwd(b.path("examples/typography"));
+        typography_driver_run.has_side_effects = true;
+        typography_driver_run.setEnvironmentVariable("NATIVE_SDK_TEST_VIEW_BACKEND", "typescript");
+        typography_driver_run.setEnvironmentVariable("NATIVE_SDK_TEST_VIEW_REFERENCE", b.pathFromRoot(".zig-cache/typography-view-reference"));
+        _ = typography_driver_run.captureStdOut(.{});
+        _ = typography_driver_run.captureStdErr(.{});
+        typography_driver_run.step.dependOn(&typography_reference_run.step);
+        b.step("test-ts-typography-driver", "Compare complete typography snapshots and replay across view backends").dependOn(&typography_driver_run.step);
+        native_driver_step.dependOn(&typography_driver_run.step);
+        ts_core_e2e_step.dependOn(&typography_driver_run.step);
+        test_step.dependOn(&typography_driver_run.step);
+
         const relational_reference_run = managedExampleRun(b, host_cli_exe, &.{ "test", "-Dplatform=null" });
         relational_reference_run.setCwd(b.path("examples/relational-notes"));
         relational_reference_run.has_side_effects = true;
@@ -1290,6 +1310,10 @@ pub fn build(b: *std.Build) void {
         addTestStep(b, "test-ts-shell-layout-e2e", "Run compiled shell planning, ownership, and OS application parity", ts_core_artifacts.shell_layout);
         ts_core_e2e_step.dependOn(&shell_layout_e2e_run.step);
         test_step.dependOn(&shell_layout_e2e_run.step);
+        const typography_run = b.addRunArtifact(ts_core_artifacts.typography);
+        b.step("test-ts-typography-e2e", "Verify compiled token overrides and registered rich paragraphs").dependOn(&typography_run.step);
+        ts_core_e2e_step.dependOn(&typography_run.step);
+        test_step.dependOn(&typography_run.step);
         const surface_layout_run = b.addRunArtifact(ts_core_artifacts.surface_layout);
         b.step("test-ts-surface-layout-e2e", "Compare compiled floating-surface placement with native layout and ABI ownership").dependOn(&surface_layout_run.step);
         ts_core_e2e_step.dependOn(&surface_layout_run.step);
@@ -1546,9 +1570,9 @@ pub fn build(b: *std.Build) void {
         .{ .path = "build/app.zig", .pattern = "break :services_contract stabilizeGeneratedFile(b, raw, \"services.contract.json\", build_trace);" },
         .{ .path = "build/app.zig", .pattern = "addAppCoreTsDirInputs(b, stage_run, appPath(b, app_root, \"src\"));" },
         .{ .path = "build/app.zig", .pattern = "addStagedCoreSdkInputs(b, dep.builder, stage_run);" },
-        .{ .path = "build/app.zig", .pattern = "for ([_][]const u8{ \"text.ts\", \"events.ts\" }) |source|" },
+        .{ .path = "build/app.zig", .pattern = "for ([_][]const u8{ \"text.ts\", \"events.ts\", \"theme.ts\" }) |source|" },
         .{ .path = "build.zig", .pattern = "app_build.addStagedCoreSdkInputs(b, b, stage_run);" },
-        .{ .path = "packages/core/scripts/stage_external_core.mjs", .pattern = "for (const sdkFile of [\"text.ts\", \"events.ts\"])" },
+        .{ .path = "packages/core/scripts/stage_external_core.mjs", .pattern = "for (const sdkFile of [\"text.ts\", \"events.ts\", \"theme.ts\"])" },
         .{ .path = "build/app.zig", .pattern = "if (std.mem.startsWith(u8, normalized, \"services/\")) continue;" },
         .{ .path = "tools/corewire/emit_service.ts", .pattern = "native-sdk.services.abi.v3" },
         .{ .path = "tools/corewire/service.test.ts", .pattern = "excludes implementation-only facts" },
@@ -2464,6 +2488,7 @@ pub fn build(b: *std.Build) void {
         addExampleTestStep(b, host_cli_exe, native_examples_step, "test-example-effect-policy", "Run named effect policy example tests", "examples/effect-policy", .managed),
         ui_inbox_example_step,
         addExampleTestStep(b, host_cli_exe, native_examples_step, "test-example-kanban", "Run ui builder kanban example tests", "examples/kanban", .managed),
+        addExampleTestStep(b, host_cli_exe, native_examples_step, "test-example-typography", "Run typography and bundled font startup tests", "examples/typography", .managed),
         addExampleTestStep(b, host_cli_exe, native_examples_step, "test-example-habits", "Run markup habits example tests", "examples/habits", .managed),
         addExampleTestStep(b, host_cli_exe, native_examples_step, "test-example-soundboard", "Run soundboard example tests", "examples/soundboard", .managed),
         addExampleTestStep(b, host_cli_exe, native_examples_step, "test-example-video-player", "Run video player example tests", "examples/video-player", .managed),
@@ -3990,6 +4015,7 @@ const TsCoreE2eArtifacts = struct {
     feed_reader: *std.Build.Step.Compile,
     shell_layout: *std.Build.Step.Compile,
     surface_layout: *std.Build.Step.Compile,
+    typography: *std.Build.Step.Compile,
     /// The phase-1 service seam: a real compiled core plus a real plain-scriptc
     /// service executable driven through the out-of-process carrier.
     services: *std.Build.Step.Compile,
@@ -4271,6 +4297,19 @@ fn tsCoreE2eArtifact(
     const shell_layout_mod = module(b, target, optimize, "tests/ts-core/shell_layout_e2e_tests.zig");
     shell_layout_mod.addImport("native_sdk", desktop_mod);
     shell_layout_mod.addImport("shell_fixture_core", feed_reader_fixture.module);
+    const typography_fixture = externalCoreFixtureModule(b, target, optimize, node, corewire_exe, .{
+        .entry = "examples/typography/src/core.ts",
+        .src_dir = b.path("examples/typography/src"),
+        .name = "typography_core",
+        .typescript_view = true,
+    });
+    const typography_mod = module(b, target, optimize, "tests/ts-core/typography_e2e_tests.zig");
+    typography_mod.addImport("native_sdk", desktop_mod);
+    typography_mod.addImport("typography_core", typography_fixture.module);
+    const typography_decoder_mod = module(b, target, optimize, "src/app_runner/ts_compiled_view.zig");
+    typography_decoder_mod.addImport("native_sdk", desktop_mod);
+    typography_decoder_mod.addImport("core.zig", typography_fixture.module);
+    typography_mod.addImport("typography_decoder", typography_decoder_mod);
     const surface_layout_mod = module(b, target, optimize, "tests/ts-core/surface_layout_e2e_tests.zig");
     surface_layout_mod.addImport("native_sdk", desktop_mod);
     surface_layout_mod.addImport("surface_fixture_core", feed_reader_fixture.module);
@@ -4542,6 +4581,7 @@ fn tsCoreE2eArtifact(
         .ai_chat = filteredTestArtifact(b, ai_chat_mod, "ts-ai-chat-e2e-tests", &.{}),
         .feed_reader = filteredTestArtifact(b, feed_reader_mod, "ts-feed-reader-e2e-tests", &.{}),
         .shell_layout = filteredTestArtifact(b, shell_layout_mod, "ts-shell-layout-e2e-tests", &.{}),
+        .typography = filteredTestArtifact(b, typography_mod, "ts-typography-e2e-tests", &.{}),
         .surface_layout = filteredTestArtifact(b, surface_layout_mod, "ts-surface-layout-e2e-tests", &.{}),
         .services = filteredTestArtifact(b, services_e2e_mod, "ts-services-e2e-tests", &.{}),
         .services_pool = if (services_pool_mod) |pool_mod| filteredTestArtifact(b, pool_mod, "ts-services-pool-e2e-tests", &.{}) else null,

build/app.zig

@@ -1476,7 +1476,7 @@ fn addAppCoreTsDirInputs(b: *std.Build, stage: *std.Build.Step.Run, src_path: []
 /// contract remains byte-identical. Public for the repository fixture graph,
 /// which exercises the same compiler boundary as app builds.
 pub fn addStagedCoreSdkInputs(b: *std.Build, sdk_builder: *std.Build, stage: *std.Build.Step.Run) void {
-    for ([_][]const u8{ "text.ts", "events.ts" }) |source| {
+    for ([_][]const u8{ "text.ts", "events.ts", "theme.ts" }) |source| {
         stage.addFileInput(sdk_builder.path(b.fmt("packages/core/sdk/{s}", .{source})));
     }
 }

docs/public/schemas/app.schema.json

@@ -213,6 +213,19 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "fonts": {
+          "type": "array",
+          "maxItems": 8,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "path"],
+            "properties": {
+              "id": { "type": "integer", "minimum": 64, "maximum": 9007199254740991 },
+              "path": { "type": "string", "pattern": "^assets/", "minLength": 8 }
+            }
+          }
+        },
         "images": {
           "type": "array",
           "items": {

examples/README.md

@@ -24,6 +24,7 @@ TypeScript is the primary app-authoring language. A new `native init my_app` pro
 | `kanban` | Keyed boards, drag interactions, avatars, controlled scrolling, and file drops. |
 | `menu-bar` | Status-item lifecycle, native menus, window hiding and reopening, and typed commands. |
 | `soundboard` | Full music player: audio effects, timers, search, assets, native context menus, and adaptive markup. |
+| `typography` | Model-derived design tokens, styled paragraphs, alignment, and bundled fonts. |
 | `system-monitor` | Subprocess effects, timers, parsing, tables, charts, controlled scroll, and confirmation flows. |
 
 Soundboard and System Monitor use the canonical unsuffixed folders. Their TypeScript cores and Native markup replace the earlier duplicate Zig implementations. New TypeScript apps need no language suffix.

examples/typography/README.md

@@ -0,0 +1,5 @@
+# Typography
+
+A TypeScript core and Native markup example of model-derived design tokens, ordered inline text styles, paragraph alignment, and a bundled TrueType font.
+
+Run `native dev`. Change size re-derives typography from the committed model; Change accent re-derives the accent and selected control. The manifest registers the mono face before the first layout. The runtime stamps device scale; omitted tokens inherit the resolved OS appearance and accessibility settings.

examples/typography/app.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://schema.native-sdk.dev/app/v1.json",
+  "id": "dev.native_sdk.typography",
+  "name": "typography",
+  "display_name": "Typography",
+  "description": "Model-derived typography and inline text styles.",
+  "version": "0.1.0",
+  "platforms": [
+    "macos"
+  ],
+  "permissions": [
+    "view",
+    "command"
+  ],
+  "capabilities": [
+    "native_views",
+    "gpu_surfaces"
+  ],
+  "assets": {
+    "fonts": [
+      {
+        "id": 64,
+        "path": "assets/GeistMono-Regular.ttf"
+      }
+    ]
+  },
+  "shell": {
+    "windows": [
+      {
+        "label": "main",
+        "title": "Typography",
+        "width": 560,
+        "height": 360,
+        "restore_policy": "center_on_primary",
+        "views": [
+          {
+            "label": "typography-canvas",
+            "kind": "gpu_surface",
+            "fill": true,
+            "gpu_backend": "metal",
+            "gpu_pixel_format": "bgra8_unorm",
+            "gpu_present_mode": "timer",
+            "gpu_color_space": "srgb",
+            "gpu_alpha_mode": "opaque",
+            "gpu_vsync": true
+          }
+        ]
+      }
+    ]
+  }
+}

examples/typography/assets/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

examples/typography/src/app.native

@@ -0,0 +1,9 @@
+<column padding="24" gap="16" grow="1">
+  <text size="display" label="{status}"><span mono="true" weight="medium">{status}</span></text>
+  <text label="Inline styles">A <span weight="bold">single</span> paragraph with <span italic="true" foreground="accent">mixed styles</span> and <span underline="true" mono="true">registered mono</span>.</text>
+  <text text-alignment="end" label="Right aligned"><span mono="true">1234567890</span></text>
+  <row gap="8">
+    <button on-press="size" label="Change size">Change size</button>
+    <button variant="primary" selected="{accent}" on-press="accent" label="Change accent">Change accent</button>
+  </row>
+</column>

examples/typography/src/core.ts

@@ -0,0 +1,16 @@
+import { asciiBytes } from "@native-sdk/core";
+import type { ThemeDesignTokenOverrides, ThemeColor } from "@native-sdk/core/theme";
+
+export interface Model { readonly large: boolean; readonly accent: boolean; }
+export type Msg = { readonly kind: "size" } | { readonly kind: "accent" };
+export function initialModel(): Model { return { large: false, accent: false }; }
+export function update(model: Model, msg: Msg): Model {
+  return msg.kind === "size" ? { ...model, large: !model.large } : { ...model, accent: !model.accent };
+}
+export function status(model: Model): Uint8Array { return asciiBytes(model.large ? "Large type" : "Regular type"); }
+export function tokenOverrides(model: Model): ThemeDesignTokenOverrides {
+  const accent: ThemeColor = { r: model.accent ? 0.125 : 0.3, g: 0.25, b: 0.9, a: 1 };
+  return { typography: { mono_font_id: 64, display_size: model.large ? 42 : 32 },
+    radius: { sm: 7, md: 10 }, colors: { accent },
+    controls: { button_primary: { active_background: accent } } };
+}