mythik 0.1.5 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/README.md +96 -36
  2. package/dist/actions/dispatcher.d.ts +2 -0
  3. package/dist/actions/dispatcher.d.ts.map +1 -1
  4. package/dist/actions/dispatcher.js +11 -2
  5. package/dist/actions/dispatcher.js.map +1 -1
  6. package/dist/actions/transaction-engine.d.ts +10 -0
  7. package/dist/actions/transaction-engine.d.ts.map +1 -1
  8. package/dist/actions/transaction-engine.js +13 -1
  9. package/dist/actions/transaction-engine.js.map +1 -1
  10. package/dist/agent-context/inventory.d.ts +62 -0
  11. package/dist/agent-context/inventory.d.ts.map +1 -0
  12. package/dist/agent-context/inventory.js +248 -0
  13. package/dist/agent-context/inventory.js.map +1 -0
  14. package/dist/contract/extractor.js +3 -0
  15. package/dist/contract/extractor.js.map +1 -1
  16. package/dist/data/data-sources.d.ts +16 -0
  17. package/dist/data/data-sources.d.ts.map +1 -1
  18. package/dist/data/data-sources.js +16 -1
  19. package/dist/data/data-sources.js.map +1 -1
  20. package/dist/editor-session/engine.d.ts +1 -0
  21. package/dist/editor-session/engine.d.ts.map +1 -1
  22. package/dist/editor-session/engine.js +5 -4
  23. package/dist/editor-session/engine.js.map +1 -1
  24. package/dist/fetch/framework-fetch.d.ts +1 -0
  25. package/dist/fetch/framework-fetch.d.ts.map +1 -1
  26. package/dist/fetch/framework-fetch.js +34 -4
  27. package/dist/fetch/framework-fetch.js.map +1 -1
  28. package/dist/fetch/interceptors/auth.d.ts +2 -0
  29. package/dist/fetch/interceptors/auth.d.ts.map +1 -1
  30. package/dist/fetch/interceptors/auth.js +31 -2
  31. package/dist/fetch/interceptors/auth.js.map +1 -1
  32. package/dist/fetch/types.d.ts +4 -0
  33. package/dist/fetch/types.d.ts.map +1 -1
  34. package/dist/index.d.ts +12 -2
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +5 -0
  37. package/dist/index.js.map +1 -1
  38. package/dist/renderer/engine.d.ts.map +1 -1
  39. package/dist/renderer/engine.js +29 -4
  40. package/dist/renderer/engine.js.map +1 -1
  41. package/dist/renderer/prop-schemas.d.ts +5 -0
  42. package/dist/renderer/prop-schemas.d.ts.map +1 -1
  43. package/dist/renderer/prop-schemas.js +11 -2
  44. package/dist/renderer/prop-schemas.js.map +1 -1
  45. package/dist/reveal/context.d.ts +22 -0
  46. package/dist/reveal/context.d.ts.map +1 -0
  47. package/dist/reveal/context.js +159 -0
  48. package/dist/reveal/context.js.map +1 -0
  49. package/dist/reveal/index.d.ts +7 -0
  50. package/dist/reveal/index.d.ts.map +1 -0
  51. package/dist/reveal/index.js +7 -0
  52. package/dist/reveal/index.js.map +1 -0
  53. package/dist/reveal/protocol.d.ts +28 -0
  54. package/dist/reveal/protocol.d.ts.map +1 -0
  55. package/dist/reveal/protocol.js +2 -0
  56. package/dist/reveal/protocol.js.map +1 -0
  57. package/dist/reveal/recorder.d.ts +20 -0
  58. package/dist/reveal/recorder.d.ts.map +1 -0
  59. package/dist/reveal/recorder.js +31 -0
  60. package/dist/reveal/recorder.js.map +1 -0
  61. package/dist/reveal/redaction.d.ts +12 -0
  62. package/dist/reveal/redaction.d.ts.map +1 -0
  63. package/dist/reveal/redaction.js +85 -0
  64. package/dist/reveal/redaction.js.map +1 -0
  65. package/dist/reveal/truncation.d.ts +4 -0
  66. package/dist/reveal/truncation.d.ts.map +1 -0
  67. package/dist/reveal/truncation.js +48 -0
  68. package/dist/reveal/truncation.js.map +1 -0
  69. package/dist/reveal/types.d.ts +104 -0
  70. package/dist/reveal/types.d.ts.map +1 -0
  71. package/dist/reveal/types.js +2 -0
  72. package/dist/reveal/types.js.map +1 -0
  73. package/dist/runtime/mount-spec-runtime.d.ts +7 -0
  74. package/dist/runtime/mount-spec-runtime.d.ts.map +1 -1
  75. package/dist/runtime/mount-spec-runtime.js +5 -1
  76. package/dist/runtime/mount-spec-runtime.js.map +1 -1
  77. package/dist/security/spec-validator.d.ts.map +1 -1
  78. package/dist/security/spec-validator.js +61 -0
  79. package/dist/security/spec-validator.js.map +1 -1
  80. package/dist/spec-stores/file.js +1 -1
  81. package/dist/spec-stores/file.js.map +1 -1
  82. package/dist/types.d.ts +8 -0
  83. package/dist/types.d.ts.map +1 -1
  84. package/docs/consumer/README.md +11 -0
  85. package/docs/consumer/WHERE-TO-LOOK.md +1 -1
  86. package/docs/consumer/ai-context-patterns.md +42 -7
  87. package/docs/consumer/ai-context-primitives.md +25 -2
  88. package/docs/consumer/ai-context-runtime-semantics.md +32 -19
  89. package/docs/consumer/ai-context.md +106 -20
  90. package/docs/consumer/reference-doc.md +170 -35
  91. package/docs/llms.txt +6 -1
  92. package/docs/wiki/compiled/README.md +13 -11
  93. package/docs/wiki/compiled/_gaps.md +1 -1
  94. package/docs/wiki/compiled/_index.md +11 -7
  95. package/docs/wiki/compiled/_inventory.md +22 -14
  96. package/docs/wiki/compiled/_lint.md +21 -17
  97. package/docs/wiki/compiled/antipattern-store-save-bypass.md +13 -8
  98. package/docs/wiki/compiled/cli-agent.md +70 -0
  99. package/docs/wiki/compiled/cli-existing-spec-edit-loop.md +9 -8
  100. package/docs/wiki/compiled/cli-overview.md +12 -7
  101. package/docs/wiki/compiled/cli-patch.md +14 -11
  102. package/docs/wiki/compiled/cli-programmatic-api.md +17 -7
  103. package/docs/wiki/compiled/cli-push.md +36 -24
  104. package/docs/wiki/compiled/cli-reveal.md +64 -0
  105. package/docs/wiki/compiled/cli-toon.md +9 -9
  106. package/docs/wiki/compiled/cli-versioning-author.md +19 -15
  107. package/docs/wiki/compiled/concept-agent-context-protocol.md +76 -0
  108. package/docs/wiki/compiled/concept-component-variants.md +39 -10
  109. package/docs/wiki/compiled/concept-mythik-reveal.md +63 -0
  110. package/docs/wiki/compiled/concept-package-layout.md +7 -6
  111. package/docs/wiki/compiled/concept-public-package-names.md +9 -5
  112. package/docs/wiki/compiled/concept-shape-animations.md +4 -2
  113. package/docs/wiki/compiled/concept-spec-store-interface.md +7 -4
  114. package/docs/wiki/compiled/concept-spec-store-layering.md +5 -5
  115. package/docs/wiki/compiled/concept-templates-vs-variants.md +77 -13
  116. package/docs/wiki/compiled/concept-versioned-store.md +8 -5
  117. package/docs/wiki/compiled/pattern-git-vs-db-versioning.md +8 -6
  118. package/docs/wiki/compiled/pattern-push-vs-patch.md +13 -12
  119. package/docs/wiki/compiled/pattern-reusable-components.md +42 -12
  120. package/package.json +1 -1
@@ -0,0 +1,76 @@
1
+ ---
2
+ id: concept-agent-context-protocol
3
+ title: Mythik Agent Context and Agent Protocol
4
+ kind: concept
5
+ sources: [docs/consumer/ai-context.md#required-edit-loop-for-existing-specs, docs/consumer/ai-context.md#rule-100, docs/consumer/reference-doc.md#rule-297]
6
+ ---
7
+
8
+ # Mythik Agent Context and Agent Protocol
9
+
10
+ Mythik Agent Context is the project-specific operating map an AI agent
11
+ reads before editing a Mythik app.
12
+
13
+ Agent Protocol is the mandatory write discipline that keeps the agent
14
+ on the validated Mythik workflow instead of drifting into full-spec
15
+ rewrites, direct database edits, or stale local files.
16
+
17
+ ## Why it exists
18
+
19
+ Fresh AI agents often know how to edit JSON but not how Mythik wants
20
+ stored specs to be changed. The protocol makes the correct behavior
21
+ local, explicit, and repeatable:
22
+
23
+ - inspect stored structure with `manifest`
24
+ - inspect exact target nodes with `elements`
25
+ - write a small RFC 6902 patch file
26
+ - apply with `patch --from-file --author`
27
+ - validate
28
+ - verify with `manifest`, `elements`, browser smoke, or Reveal
29
+
30
+ ## Store-backed source of truth
31
+
32
+ For DB-backed Mythik projects, the active store is the source of
33
+ truth. Local spec files are drafts, snapshots, migrations, backups, or
34
+ fixtures. They are not the canonical document unless the project has
35
+ intentionally configured a file store.
36
+
37
+ This prevents the common failure where an agent patches the database
38
+ correctly, then overwrites the result from an older local `spec.json`.
39
+
40
+ ## Strict write intent
41
+
42
+ Persisted writes are strict by default:
43
+
44
+ - Existing full-spec replacement requires `--replace`.
45
+ - Normal persisted writes use `--author <name>`.
46
+ - `--allow-unversioned` is only for intentionally unversioned stores.
47
+
48
+ These guardrails preserve version history and make destructive writes
49
+ explicit.
50
+
51
+ ## Relationship to Reveal
52
+
53
+ Agent Protocol edits stored specs. Mythik Reveal inspects the running
54
+ app.
55
+
56
+ Use both:
57
+
58
+ - `manifest` / `elements` / `patch` to change the stored contract.
59
+ - `reveal current`, `reveal screen`, or `reveal element` to understand
60
+ runtime state, resolved props, warnings, render errors, and events
61
+ before guessing.
62
+
63
+ ## Related articles
64
+
65
+ - [[@cli-agent]]
66
+ - [[@cli-existing-spec-edit-loop]]
67
+ - [[@cli-versioning-author]]
68
+ - [[@cli-reveal]]
69
+ - [[@concept-mythik-reveal]]
70
+ - [[@concept-source-of-truth-references]]
71
+ - [[@pattern-push-vs-patch]]
72
+
73
+ ## Sources
74
+
75
+ - `docs/consumer/ai-context.md`
76
+ - `docs/consumer/reference-doc.md`
@@ -7,9 +7,17 @@ sources: [docs/consumer/ai-context.md#component-variants, docs/consumer/referenc
7
7
 
8
8
  # Component variants
9
9
 
10
- Token-driven component styling. Define variant definitions in
11
- `tokens.components.{primitiveType}.{variantName}`. The engine applies
12
- style, hover, active, focus, transition, animations automatically.
10
+ Token-driven component styling. Define variant definitions in
11
+ `tokens.components.{primitiveType}.{variantName}`. The engine applies
12
+ style, hover, active, focus, transition, animations automatically.
13
+
14
+ Use variants before copying the same visual style block into multiple
15
+ elements. Variants are intentionally limited to primitive visual slots:
16
+ `style`, `hover`, `active`, `focus`, `transition`, and `animations`.
17
+ They do not carry arbitrary primitive props such as table `headerStyle`,
18
+ table `rowStyle`, `columns`, `onRowClick`, action bindings, or child
19
+ composition. Use [[@concept-templates-vs-variants]] when the repeated
20
+ pattern needs those props.
13
21
 
14
22
  ## Defining
15
23
 
@@ -49,9 +57,28 @@ style, hover, active, focus, transition, animations automatically.
49
57
  `variant` is **universal** — any primitive can use it when defined in
50
58
  `tokens.components`.
51
59
 
52
- ## Supported variant fields
53
-
54
- `style`, `hover`, `active`, `focus`, `transition`, `animations`.
60
+ ## Supported variant fields
61
+
62
+ `style`, `hover`, `active`, `focus`, `transition`, `animations`.
63
+
64
+ ## Not supported inside primitive variants
65
+
66
+ Do not put these in `tokens.components.{type}.{variant}` and expect the
67
+ primitive to receive them:
68
+
69
+ - `headerStyle` / `rowStyle` on `table`
70
+ - `columns`, `pagination`, `selection`, `groupBy`, `onRowClick`
71
+ - action bindings
72
+ - composed children
73
+
74
+ For reusable table chrome, put the surrounding card style in a `box`
75
+ variant and wrap the `table` in an AppSpec template that passes
76
+ `headerStyle`, `rowStyle`, `columns`, and actions through `$prop`.
77
+
78
+ For filter chips composed from `touchable` + `text`, keep static shell
79
+ and label styling in variants, then keep active `$state` / `$item`
80
+ expressions on the actual elements. Variants do not evaluate render
81
+ context expressions such as `$state`, `$item`, or `$prop` by themselves.
55
82
 
56
83
  ## `$path` references
57
84
 
@@ -70,10 +97,12 @@ Variant is base, element-level overrides — same as CSS class + inline
70
97
  override. Hover merges per-key (variant's `scale: 1.05` + element's
71
98
  `rotate: 5` both apply).
72
99
 
73
- ## Constraints / Anti-patterns
74
-
75
- - **Place `variant` in `props`**, not as a top-level field. Top-level is
76
- silently ignored. See [[@antipattern-element-variant-top-level]].
100
+ ## Constraints / Anti-patterns
101
+
102
+ - **Place `variant` in `props`**, not as a top-level field. Top-level is
103
+ silently ignored. See [[@antipattern-element-variant-top-level]].
104
+ - **Do not copy table chrome into every table.** Use a template for the
105
+ prop-bearing table defaults and a variant for the panel/card shell.
77
106
 
78
107
  ## Related concepts
79
108
 
@@ -0,0 +1,63 @@
1
+ ---
2
+ id: concept-mythik-reveal
3
+ title: Mythik Reveal - live runtime context for AI agents
4
+ kind: concept
5
+ sources: [docs/consumer/ai-context.md#mythik-reveal-live-context-for-ai-agents, docs/consumer/reference-doc.md#mythik-reveal--live-runtime-context-for-ai-agents]
6
+ ---
7
+
8
+ # Mythik Reveal
9
+
10
+ Mythik Reveal lets a running Mythik app expose its live contract, state,
11
+ actions, diagnostics, environment, and render errors as structured
12
+ context for AI agents.
13
+
14
+ Reveal is for runtime truth. It complements the normal spec workflow:
15
+
16
+ - `manifest` and `elements` read stored specs.
17
+ - `lint` and `validate` check candidate specs.
18
+ - `patch --from-file` writes validated changes.
19
+ - Reveal reads the app that is actually running.
20
+
21
+ Use Reveal before guessing when a runtime symptom is visible: a button
22
+ does not fire, a screen renders the wrong branch, a dataSource fails,
23
+ a render error appears, or React Native behaves differently from web.
24
+
25
+ ## What Reveal exposes
26
+
27
+ Reveal context can include:
28
+
29
+ - renderer and platform (`react`, `react-native`, `android`, etc.)
30
+ - app and environment metadata
31
+ - mounted spec summary
32
+ - selected screen or element context
33
+ - resolved public props and element dependency paths
34
+ - selected state paths, with redaction
35
+ - render errors and warnings
36
+ - action, transaction, dataSource, navigation, lifecycle, and render
37
+ error events
38
+ - patch target metadata when available
39
+ - redaction and truncation metadata
40
+
41
+ ## Security contract
42
+
43
+ Reveal is development tooling.
44
+
45
+ - Do not enable it in production.
46
+ - Do not commit or publish Reveal tokens.
47
+ - Use narrow `includeStatePaths`.
48
+ - Redact `/auth`, `/secrets`, tokens, passwords, API keys, and session
49
+ values.
50
+ - Memoize React and React Native `reveal` config objects so bridge
51
+ clients stay stable across renders.
52
+
53
+ ## Related articles
54
+
55
+ - [[@cli-reveal]]
56
+ - [[@cli-existing-spec-edit-loop]]
57
+ - [[@concept-debugging-runtime-pointers]]
58
+ - [[@concept-render-error-visibility]]
59
+
60
+ ## Sources
61
+
62
+ - `docs/consumer/ai-context.md`
63
+ - `docs/consumer/reference-doc.md`
@@ -13,12 +13,13 @@ sources: [docs/consumer/ai-context.md, docs/consumer/WHERE-TO-LOOK.md]
13
13
  |---|---|
14
14
  | `mythik` | Browser-safe core. State, expressions, validation, renderer engine, design, auth, data, security, and browser-safe spec stores |
15
15
  | `mythik/server` | Node-only spec stores, SQL drivers, and SQL DDL helpers: `FileSpecStore`, `SqlSpecStore`, `SqlVersionedSpecStore`, `SqlEnvironmentStore`, `createSqlDriver`, `getSqlStoreDdl`, and SQL Server compatibility stores |
16
- | `mythik-react` | React host, renderer, and web primitives |
17
- | `mythik-cli` | CLI package; installs the `mythik` command |
18
- | `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, `parsePatchInput`, and types |
19
- | `mythik-server` | Express server runtime for ApiSpecs |
20
-
21
- React Native work lives in the repository as a preview track and is not part of the supported npm publish surface yet.
16
+ | `mythik-react` | React host, renderer, and web primitives |
17
+ | `mythik-react-native` | React Native and Expo renderer, public preview, with an explicit primitive support matrix |
18
+ | `mythik-cli` | CLI package; installs the `mythik` command |
19
+ | `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, `parsePatchInput`, and types |
20
+ | `mythik-server` | Express server runtime for ApiSpecs |
21
+
22
+ `mythik-react-native` is published on the same version line as the rest of Mythik, but remains a public preview while native primitive parity and smoke coverage continue to expand.
22
23
 
23
24
  ## Browser vs server core entries
24
25
 
@@ -13,10 +13,11 @@ Mythik publishes unscoped npm packages. Do not generate scoped package imports f
13
13
  |---|---|
14
14
  | `mythik` | Browser-safe core runtime, state, expressions, validation, browser-safe stores |
15
15
  | `mythik/server` | Node-only stores, SQL drivers, and SQL DDL helpers exported from the core package subpath |
16
- | `mythik-react` | React host, renderer, and web primitives |
17
- | `mythik-cli` | CLI package; installs the `mythik` binary |
18
- | `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, and related types |
19
- | `mythik-server` | Express server runtime for ApiSpecs |
16
+ | `mythik-react` | React host, renderer, and web primitives |
17
+ | `mythik-react-native` | React Native and Expo renderer, public preview, with an explicit primitive support matrix |
18
+ | `mythik-cli` | CLI package; installs the `mythik` binary |
19
+ | `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, and related types |
20
+ | `mythik-server` | Express server runtime for ApiSpecs |
20
21
 
21
22
  The `mythik` package also ships the AI documentation under `node_modules/mythik/docs`.
22
23
  Use [[@cli-docs]] to locate or copy it after install.
@@ -28,7 +29,10 @@ npm install mythik mythik-react
28
29
  npm install -D mythik-cli
29
30
  ```
30
31
 
31
- Add `mythik-server` only when building a Mythik-backed Node server. React Native work is a repository preview track, not part of the supported npm publish surface yet.
32
+ Add `mythik-server` only when building a Mythik-backed Node server.
33
+ For React Native and Expo, install `mythik mythik-react-native`; Expo
34
+ apps should install native peer packages with `npx expo install ...`
35
+ so Expo selects versions compatible with the app SDK.
32
36
 
33
37
  SQL adapters (`mssql`, `pg`, `mysql2`, `better-sqlite3`) are optional peer dependencies. Install only the selected database adapter:
34
38
 
@@ -29,8 +29,10 @@ useShapeAnimations(ref, animations, options)
29
29
 
30
30
  ## RN variant
31
31
 
32
- `packages/react-native/src/animation/useShapeAnimations.ts` — repository
33
- preview implementation. It is not part of the supported npm publish surface yet.
32
+ `packages/react-native/src/animation/useShapeAnimations.ts` — internal
33
+ implementation used by the public-preview native blob/background renderer.
34
+ It is not exported from the `mythik-react-native` package root as a standalone
35
+ public hook.
34
36
 
35
37
  ```ts
36
38
  useShapeAnimations(animations, options) → { animatedProps }
@@ -32,10 +32,13 @@ readers without breaking the consumer adapter contract.**
32
32
 
33
33
  ## Approved consumer paths (3 forms)
34
34
 
35
- Never call `SpecStore.save()` from app code. Use:
36
- - **Shell**: `mythik push <id> --from-file spec.json`
37
- - **Bulk**: `mythik push --from-dir <folder>`
38
- - **Programmatic**: `runPush` / `runPatch` from `mythik-cli/api`
35
+ Never call `SpecStore.save()` from app code. Use:
36
+ - **Shell**: `mythik push <id> --from-file spec.json --author <agent>` or `mythik patch <id> --from-file patch.json --author <agent>`
37
+ - **Bulk**: `mythik push --from-dir <folder> --author <agent>`
38
+ - **Programmatic**: `runPush` / `runPatch` from `mythik-cli/api` with `author`
39
+
40
+ Existing full-spec replacement requires explicit `--replace`. Intentionally
41
+ unversioned stores require explicit `--allow-unversioned`.
39
42
 
40
43
  See [[@cli-push]] + [[@antipattern-store-save-bypass]].
41
44
 
@@ -18,14 +18,14 @@ Understanding the layering prevents bypassing validation.
18
18
  | `store.saveVersion(id, doc, meta)` | **NO** | Versioned write. Writes to `screen_versions` and updates the current spec. |
19
19
  | `SpecEngine.patch(id, patches)` | **YES** | Applies RFC-6902 patches, validates through the document handler, and persists the patched document through `store.save`. |
20
20
  | `mythik push` / `runPush` | **YES** | Validates and writes through `saveVersion` when a versioned store + author are used. |
21
- | `mythik patch` / `runPatch` | **YES** | Uses `SpecEngine.patch` for patch application + validation. Without author, persists through `store.save`; with a versioned store + author, captures the patched document and writes once through `saveVersion`. |
21
+ | `mythik patch` / `runPatch` | **YES** | Uses `SpecEngine.patch` for patch application + validation. With a versioned store + author, captures the patched document and writes once through `saveVersion`. Without author, persisted writes are rejected unless `--allow-unversioned` is explicit. |
22
22
 
23
23
  ## Consumer rule
24
24
 
25
- **Never call `store.save()` from application code.** Use:
26
-
27
- - `mythik push <id>` / `mythik patch <id> --from-file patch.json` for shell work.
28
- - `runPush` / `runPatch` from `mythik-cli/api` for programmatic work.
25
+ **Never call `store.save()` from application code.** Use:
26
+
27
+ - `mythik push <id> --from-file spec.json --author <agent>` / `mythik patch <id> --from-file patch.json --author <agent>` for shell work.
28
+ - `runPush` / `runPatch` from `mythik-cli/api` with `author` for programmatic work.
29
29
 
30
30
  See [[@antipattern-store-save-bypass]] and [[@cli-lint]].
31
31
 
@@ -11,19 +11,36 @@ Two underused reuse mechanisms. **Use them before duplicating style blocks.**
11
11
 
12
12
  ## Decision table
13
13
 
14
- | Situation | Pick |
15
- |---|---|
16
- | Same primitive type, different style set | `tokens.components.{type}.{variant}` |
17
- | Composite (custom type wrapping primitive + children slot) | `appSpec.templates` |
18
- | Style varies by state (hover/active/focus) | Variants (built-in state slots) |
19
- | Parametrized via props + children | Templates (with `$prop` + `$children`) |
14
+ | Situation | Pick |
15
+ |---|---|
16
+ | Same primitive type, different style set | `tokens.components.{type}.{variant}` |
17
+ | Primitive style plus repeated primitive props such as table `headerStyle` / `rowStyle` | `appSpec.templates` |
18
+ | Composite (custom type wrapping primitive + children slot) | `appSpec.templates` |
19
+ | Style varies by state (hover/active/focus) | Variants (built-in state slots) |
20
+ | Parametrized via props + children | Templates (with `$prop` + `$children`) |
20
21
 
21
22
  ## Trade-off
22
23
 
23
- - **Variants are lightweight** and integrate natively with primitive
24
- rendering. Prefer when you only vary style.
25
- - **Templates are more flexible** but more verbose. Use when you compose
26
- structure (different children, parametrized props beyond style).
24
+ - **Variants are lightweight** and integrate natively with primitive
25
+ rendering. Prefer when you only vary style, hover, active, focus,
26
+ transition, or animations.
27
+ - **Templates are more flexible** but more verbose. Use when you compose
28
+ structure or need reusable primitive props beyond visual slots.
29
+
30
+ ## Important boundary
31
+
32
+ `tokens.components` variants do not carry arbitrary primitive props.
33
+ For example, a `table` variant is not the right place for `headerStyle`,
34
+ `rowStyle`, `columns`, `pagination`, `selection`, `groupBy`, or
35
+ `onRowClick`. Those are primitive props, not variant visual slots.
36
+
37
+ Use a template when the repeated pattern needs those props:
38
+
39
+ - `box.tableCard` variant for the shared panel shell.
40
+ - `ops-table` template for the actual table with shared `headerStyle`
41
+ and `rowStyle`.
42
+ - `$prop` pass-through for screen-specific `data`, `columns`, actions,
43
+ pagination, selection, grouping, and empty states.
27
44
 
28
45
  ## Example — variant (style-only)
29
46
 
@@ -60,9 +77,56 @@ Use: `{ "type": "button", "props": { "variant": "ctaPulse", "label": "..." } }`.
60
77
  }
61
78
  ```
62
79
 
63
- Use: `{ "type": "button-pulse-cta", "props": { "label": "Sign Up", "padding": "10px 20px" } }`.
64
-
65
- ## Animations cascade across both
80
+ Use: `{ "type": "button-pulse-cta", "props": { "label": "Sign Up", "padding": "10px 20px" } }`.
81
+
82
+ ## Example -> table chrome template
83
+
84
+ ```json
85
+ {
86
+ "tokens": {
87
+ "components": {
88
+ "box": {
89
+ "tableCard": {
90
+ "style": {
91
+ "backgroundColor": "#FFFFFF",
92
+ "border": "1px solid #E2E8F0",
93
+ "borderRadius": 16,
94
+ "padding": 12
95
+ }
96
+ }
97
+ }
98
+ }
99
+ },
100
+ "templates": {
101
+ "ops-table": {
102
+ "type": "table",
103
+ "props": {
104
+ "data": { "$prop": "data" },
105
+ "columns": { "$prop": "columns" },
106
+ "headerStyle": { "minHeight": 44, "background": "#F8FAFC" },
107
+ "rowStyle": {
108
+ "base": { "minHeight": 43 },
109
+ "hover": { "backgroundColor": "#F8FAFC" }
110
+ },
111
+ "pagination": { "$prop": "pagination" },
112
+ "onRowClick": { "$prop": "onRowClick" }
113
+ }
114
+ }
115
+ }
116
+ }
117
+ ```
118
+
119
+ Use the card variant around the template:
120
+
121
+ ```json
122
+ {
123
+ "type": "box",
124
+ "props": { "variant": "tableCard" },
125
+ "children": ["orders-table"]
126
+ }
127
+ ```
128
+
129
+ ## Animations cascade across both
66
130
 
67
131
  `animations` declared at any of these levels merges via the cascade —
68
132
  identity → variant → elementDef → template → element. See
@@ -21,9 +21,11 @@ currentVersion(id): Promise<number>
21
21
 
22
22
  ## Activation
23
23
 
24
- `mythik push --author <name>` and `mythik patch --author <name>` activate
25
- versioning automatically. Without `--author`, commands work as before
26
- (no versioning).
24
+ `mythik push --author <name>` and `mythik patch --author <name>` activate
25
+ versioning automatically when the resolved store supports
26
+ `saveVersion`. Without `--author`, persisted writes are rejected unless
27
+ `--allow-unversioned` is explicit. Existing full-spec replacement
28
+ requires `--replace`.
27
29
 
28
30
  ## Snapshots + patch chain
29
31
 
@@ -57,8 +59,9 @@ See `concept-customize-versioned-store.md` for the recipe.
57
59
  - [[@cli-versioning-author]]
58
60
  - [[@cli-history]]
59
61
  - [[@concept-rollback]]
60
- - [[@concept-environment-store]]
61
- - [[@concept-customize-versioned-store]]
62
+ - [[@concept-environment-store]]
63
+ - [[@concept-customize-versioned-store]]
64
+ - [[@concept-agent-context-protocol]]
62
65
 
63
66
  ## Sources (raw)
64
67
 
@@ -9,12 +9,14 @@ sources: [docs/consumer/ai-context-runtime-semantics.md#62-git-backed-vs-db-vers
9
9
 
10
10
  Two history models — pick one per project.
11
11
 
12
- ## Git-backed history
13
-
14
- - Specs in repo, `git log` + `git blame` serve as audit trail.
15
- - No `--author` flag needed on push/patch.
16
- - CLI writes via `store.save` (unversioned path).
17
- - **Best for**: single-env apps, dev-loop iteration, specs-as-code.
12
+ ## Git-backed history
13
+
14
+ - Specs in repo, `git log` + `git blame` serve as audit trail.
15
+ - Persisted CLI writes must still be explicit: use `--author <name>`
16
+ when the resolved store supports versioning, or `--allow-unversioned`
17
+ only when the project intentionally uses a non-versioned store.
18
+ - CLI writes via `store.save` only on the explicit unversioned path.
19
+ - **Best for**: single-env apps, dev-loop iteration, specs-as-code.
18
20
 
19
21
  ## DB-versioned history
20
22
 
@@ -10,18 +10,19 @@ sources: [docs/consumer/ai-context-runtime-semantics.md#61-push-vs-patch--file-f
10
10
  Two paradigms for modifying specs. Pick one per project; mixing creates
11
11
  issues.
12
12
 
13
- ## Push paradigm (file-first)
14
-
15
- - Specs live in git under `specs/*.json`.
16
- - Modify locally, then run `mythik push <id>`.
17
- - Diff-reviewable in CI through normal JSON file diffs.
18
- - Full-spec bandwidth cost per write.
19
-
20
- ## Patch paradigm (DB-first)
21
-
22
- - Specs live in the DB; local files are optional working snapshots.
23
- - Modify via `mythik patch <id> --from-file patch.json` for shell-safe
24
- surgical writes.
13
+ ## Push paradigm (file-first)
14
+
15
+ - Specs live in git under `specs/*.json`.
16
+ - Modify locally, lint, then run `mythik push <id> --from-file spec.json --author <agent>`.
17
+ - Existing persisted specs require explicit `--replace` for full replacement.
18
+ - Diff-reviewable in CI through normal JSON file diffs.
19
+ - Full-spec bandwidth cost per write.
20
+
21
+ ## Patch paradigm (DB-first)
22
+
23
+ - Specs live in the DB; local files are optional working snapshots.
24
+ - Modify via `mythik patch <id> --from-file patch.json --author <agent>` for shell-safe
25
+ surgical writes.
25
26
  - Requires `mythik pull <id>` to refresh any local `specs/*.json` snapshot
26
27
  after a DB patch.
27
28
 
@@ -12,12 +12,13 @@ style blocks.**
12
12
 
13
13
  ## Decision
14
14
 
15
- | Need | Pick |
16
- |---|---|
17
- | Same primitive type, different style set | `tokens.components.{type}.{variant}` |
18
- | Composite (custom type wrapping primitive + children slot) | `appSpec.templates` |
19
- | Style varies by state (hover/active/focus) | Variants (built-in state slots) |
20
- | Parametrized via props + children | Templates (with `$prop` + `$children`) |
15
+ | Need | Pick |
16
+ |---|---|
17
+ | Same primitive type, different style set | `tokens.components.{type}.{variant}` |
18
+ | Primitive style plus repeated primitive props such as table `headerStyle` / `rowStyle` | `appSpec.templates` |
19
+ | Composite (custom type wrapping primitive + children slot) | `appSpec.templates` |
20
+ | Style varies by state (hover/active/focus) | Variants (built-in state slots) |
21
+ | Parametrized via props + children | Templates (with `$prop` + `$children`) |
21
22
 
22
23
  See [[@concept-templates-vs-variants]] for the full decision walk-through.
23
24
 
@@ -35,7 +36,22 @@ If the same rich style object appears in 2+ specs (or 2+ places in same
35
36
  spec), extract to a template or variant. Duplication inflates DB storage,
36
37
  breaks DRY, makes updates O(N).
37
38
 
38
- See [[@antipattern-style-block-duplication]].
39
+ See [[@antipattern-style-block-duplication]].
40
+
41
+ ## Boundary: style reuse vs prop-bearing reuse
42
+
43
+ Variants cover primitive visual slots only: `style`, `hover`, `active`,
44
+ `focus`, `transition`, and `animations`. Do not use variants for table
45
+ `headerStyle`, table `rowStyle`, `columns`, `onRowClick`, action bindings,
46
+ or composed children.
47
+
48
+ Use both mechanisms together when needed:
49
+
50
+ - `tokens.components.box.tableCard` for a repeated table panel shell.
51
+ - `appSpec.templates.ops-table` for the table itself, including shared
52
+ `headerStyle` / `rowStyle` and `$prop` pass-through.
53
+ - static `touchable` / `text` variants for filter chip shell and label
54
+ style, with active `$state` / `$item` styling kept on the actual elements.
39
55
 
40
56
  ## Right approach — extract once
41
57
 
@@ -43,11 +59,25 @@ See [[@antipattern-style-block-duplication]].
43
59
  // appSpec.templates once
44
60
  { "templates": { "button-pulse-cta": { ...full definition... } } }
45
61
 
46
- // both screens
47
- { "type": "button-pulse-cta", "props": { "label": "..." } }
48
- ```
49
-
50
- ## Animations cascade across BOTH mechanisms
62
+ // both screens
63
+ { "type": "button-pulse-cta", "props": { "label": "..." } }
64
+ ```
65
+
66
+ For repeated table chrome:
67
+
68
+ ```json
69
+ // appSpec tokens once
70
+ { "tokens": { "components": { "box": { "tableCard": { "style": { "...": "..." } } } } } }
71
+
72
+ // appSpec template once
73
+ { "templates": { "ops-table": { "type": "table", "props": { "headerStyle": { "...": "..." }, "rowStyle": { "...": "..." }, "columns": { "$prop": "columns" }, "data": { "$prop": "data" } } } } }
74
+
75
+ // each screen
76
+ { "type": "box", "props": { "variant": "tableCard" }, "children": ["orders-table"] }
77
+ { "type": "ops-table", "props": { "data": { "$state": "/orders" }, "columns": [...] } }
78
+ ```
79
+
80
+ ## Animations cascade across BOTH mechanisms
51
81
 
52
82
  `animations` declared at any of these levels merges via the cascade —
53
83
  identity → variant → template → element — with per-trigger null semantics.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mythik",
3
- "version": "0.1.5",
3
+ "version": "0.2.1",
4
4
  "description": "AI-first JSON-native core runtime for validated applications, APIs, editor sessions, state, actions, validation, and versioning.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",