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.
- package/README.md +96 -36
- package/dist/actions/dispatcher.d.ts +2 -0
- package/dist/actions/dispatcher.d.ts.map +1 -1
- package/dist/actions/dispatcher.js +11 -2
- package/dist/actions/dispatcher.js.map +1 -1
- package/dist/actions/transaction-engine.d.ts +10 -0
- package/dist/actions/transaction-engine.d.ts.map +1 -1
- package/dist/actions/transaction-engine.js +13 -1
- package/dist/actions/transaction-engine.js.map +1 -1
- package/dist/agent-context/inventory.d.ts +62 -0
- package/dist/agent-context/inventory.d.ts.map +1 -0
- package/dist/agent-context/inventory.js +248 -0
- package/dist/agent-context/inventory.js.map +1 -0
- package/dist/contract/extractor.js +3 -0
- package/dist/contract/extractor.js.map +1 -1
- package/dist/data/data-sources.d.ts +16 -0
- package/dist/data/data-sources.d.ts.map +1 -1
- package/dist/data/data-sources.js +16 -1
- package/dist/data/data-sources.js.map +1 -1
- package/dist/editor-session/engine.d.ts +1 -0
- package/dist/editor-session/engine.d.ts.map +1 -1
- package/dist/editor-session/engine.js +5 -4
- package/dist/editor-session/engine.js.map +1 -1
- package/dist/fetch/framework-fetch.d.ts +1 -0
- package/dist/fetch/framework-fetch.d.ts.map +1 -1
- package/dist/fetch/framework-fetch.js +34 -4
- package/dist/fetch/framework-fetch.js.map +1 -1
- package/dist/fetch/interceptors/auth.d.ts +2 -0
- package/dist/fetch/interceptors/auth.d.ts.map +1 -1
- package/dist/fetch/interceptors/auth.js +31 -2
- package/dist/fetch/interceptors/auth.js.map +1 -1
- package/dist/fetch/types.d.ts +4 -0
- package/dist/fetch/types.d.ts.map +1 -1
- package/dist/index.d.ts +12 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -1
- package/dist/renderer/engine.d.ts.map +1 -1
- package/dist/renderer/engine.js +29 -4
- package/dist/renderer/engine.js.map +1 -1
- package/dist/renderer/prop-schemas.d.ts +5 -0
- package/dist/renderer/prop-schemas.d.ts.map +1 -1
- package/dist/renderer/prop-schemas.js +11 -2
- package/dist/renderer/prop-schemas.js.map +1 -1
- package/dist/reveal/context.d.ts +22 -0
- package/dist/reveal/context.d.ts.map +1 -0
- package/dist/reveal/context.js +159 -0
- package/dist/reveal/context.js.map +1 -0
- package/dist/reveal/index.d.ts +7 -0
- package/dist/reveal/index.d.ts.map +1 -0
- package/dist/reveal/index.js +7 -0
- package/dist/reveal/index.js.map +1 -0
- package/dist/reveal/protocol.d.ts +28 -0
- package/dist/reveal/protocol.d.ts.map +1 -0
- package/dist/reveal/protocol.js +2 -0
- package/dist/reveal/protocol.js.map +1 -0
- package/dist/reveal/recorder.d.ts +20 -0
- package/dist/reveal/recorder.d.ts.map +1 -0
- package/dist/reveal/recorder.js +31 -0
- package/dist/reveal/recorder.js.map +1 -0
- package/dist/reveal/redaction.d.ts +12 -0
- package/dist/reveal/redaction.d.ts.map +1 -0
- package/dist/reveal/redaction.js +85 -0
- package/dist/reveal/redaction.js.map +1 -0
- package/dist/reveal/truncation.d.ts +4 -0
- package/dist/reveal/truncation.d.ts.map +1 -0
- package/dist/reveal/truncation.js +48 -0
- package/dist/reveal/truncation.js.map +1 -0
- package/dist/reveal/types.d.ts +104 -0
- package/dist/reveal/types.d.ts.map +1 -0
- package/dist/reveal/types.js +2 -0
- package/dist/reveal/types.js.map +1 -0
- package/dist/runtime/mount-spec-runtime.d.ts +7 -0
- package/dist/runtime/mount-spec-runtime.d.ts.map +1 -1
- package/dist/runtime/mount-spec-runtime.js +5 -1
- package/dist/runtime/mount-spec-runtime.js.map +1 -1
- package/dist/security/spec-validator.d.ts.map +1 -1
- package/dist/security/spec-validator.js +61 -0
- package/dist/security/spec-validator.js.map +1 -1
- package/dist/spec-stores/file.js +1 -1
- package/dist/spec-stores/file.js.map +1 -1
- package/dist/types.d.ts +8 -0
- package/dist/types.d.ts.map +1 -1
- package/docs/consumer/README.md +11 -0
- package/docs/consumer/WHERE-TO-LOOK.md +1 -1
- package/docs/consumer/ai-context-patterns.md +42 -7
- package/docs/consumer/ai-context-primitives.md +25 -2
- package/docs/consumer/ai-context-runtime-semantics.md +32 -19
- package/docs/consumer/ai-context.md +106 -20
- package/docs/consumer/reference-doc.md +170 -35
- package/docs/llms.txt +6 -1
- package/docs/wiki/compiled/README.md +13 -11
- package/docs/wiki/compiled/_gaps.md +1 -1
- package/docs/wiki/compiled/_index.md +11 -7
- package/docs/wiki/compiled/_inventory.md +22 -14
- package/docs/wiki/compiled/_lint.md +21 -17
- package/docs/wiki/compiled/antipattern-store-save-bypass.md +13 -8
- package/docs/wiki/compiled/cli-agent.md +70 -0
- package/docs/wiki/compiled/cli-existing-spec-edit-loop.md +9 -8
- package/docs/wiki/compiled/cli-overview.md +12 -7
- package/docs/wiki/compiled/cli-patch.md +14 -11
- package/docs/wiki/compiled/cli-programmatic-api.md +17 -7
- package/docs/wiki/compiled/cli-push.md +36 -24
- package/docs/wiki/compiled/cli-reveal.md +64 -0
- package/docs/wiki/compiled/cli-toon.md +9 -9
- package/docs/wiki/compiled/cli-versioning-author.md +19 -15
- package/docs/wiki/compiled/concept-agent-context-protocol.md +76 -0
- package/docs/wiki/compiled/concept-component-variants.md +39 -10
- package/docs/wiki/compiled/concept-mythik-reveal.md +63 -0
- package/docs/wiki/compiled/concept-package-layout.md +7 -6
- package/docs/wiki/compiled/concept-public-package-names.md +9 -5
- package/docs/wiki/compiled/concept-shape-animations.md +4 -2
- package/docs/wiki/compiled/concept-spec-store-interface.md +7 -4
- package/docs/wiki/compiled/concept-spec-store-layering.md +5 -5
- package/docs/wiki/compiled/concept-templates-vs-variants.md +77 -13
- package/docs/wiki/compiled/concept-versioned-store.md +8 -5
- package/docs/wiki/compiled/pattern-git-vs-db-versioning.md +8 -6
- package/docs/wiki/compiled/pattern-push-vs-patch.md +13 -12
- package/docs/wiki/compiled/pattern-reusable-components.md +42 -12
- 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-
|
|
18
|
-
| `mythik-cli
|
|
19
|
-
| `mythik-
|
|
20
|
-
|
|
21
|
-
|
|
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-
|
|
18
|
-
| `mythik-cli
|
|
19
|
-
| `mythik-
|
|
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.
|
|
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` —
|
|
33
|
-
|
|
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.
|
|
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
|
|
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
|
-
|
|
|
18
|
-
|
|
|
19
|
-
|
|
|
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
|
-
|
|
26
|
-
|
|
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
|
-
##
|
|
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
|
|
26
|
-
|
|
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
|
-
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
-
-
|
|
18
|
-
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
-
|
|
24
|
-
|
|
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
|
-
|
|
|
19
|
-
|
|
|
20
|
-
|
|
|
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
|
-
|
|
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