@kensnzk/koyu 0.23.0 → 0.24.0

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.
@@ -0,0 +1,64 @@
1
+ // koyu — reading back what was written, from a mark or a scene node (`@kensnzk/koyu/draw`)
2
+ //
3
+ // `Mark.written` and `SceneNode.written` give a place in **canonical boundary order**. Reaching the
4
+ // attributes from that place needs the model, and needs it read in exactly one way: `Form`'s index
5
+ // is an index into `canonicalBoundaryOrder(model)`, never into `model.boundaries`. Declaration
6
+ // order is information the canonical form discards, so indexing by it does not throw — **it reads
7
+ // another boundary's `spec`**, on some models and not others (ADR-0041).
8
+ //
9
+ // **Why this and not the ordering function itself.** Two things go wrong when a consumer holds the
10
+ // sorted array. It sorts per lookup — both viewers did, once per boundary, re-sorting the whole
11
+ // building each time, which is the cost ADR-0041 names. And the raw array invites
12
+ // `model.boundaries[i]` to be substituted for it by anyone who does not know the difference, which
13
+ // is the failure the ordering exists to prevent. A window that answers "what was written here"
14
+ // closes both: sorted once per model, and there is no array to mis-index.
15
+ //
16
+ // This lives in the presentation face because it is not part of the language. `spec` is a carried
17
+ // free word — core neither reads it nor promises what it means (docs/reference/muro/attributes.md);
18
+ // only a drawing ever asks.
19
+ import { canonicalBoundaryOrder, type Model } from "../core/model.js";
20
+
21
+ /** What a model wrote at a place the `Form` points to. */
22
+ export interface Written {
23
+ /** the `spec` on a boundary, by its place in canonical order */
24
+ boundarySpec(boundary: number): string | undefined;
25
+ /** the `spec` on a segment that does not count */
26
+ segSpec(boundary: number, index: number): string | undefined;
27
+ /** the `spec` on an opening */
28
+ openingSpec(boundary: number, index: number): string | undefined;
29
+ /** any carried attribute on a boundary, including a namespaced one */
30
+ boundaryAttr(boundary: number, key: string): string | number | boolean | undefined;
31
+ /** any carried attribute on an opening */
32
+ openingAttr(boundary: number, index: number, key: string): string | number | boolean | undefined;
33
+ }
34
+
35
+ // A model is a value, so the answer for one never changes. Sorting is O(n log n) over every
36
+ // boundary; doing it once per model is the whole point of the cache.
37
+ const cache = new WeakMap<Model, Written>();
38
+
39
+ /**
40
+ * A window onto what a model wrote, addressed the way `Form` addresses it.
41
+ *
42
+ * ```ts
43
+ * const written = writtenOf(model);
44
+ * for (const n of sceneOf(form).nodes) {
45
+ * const spec = n.written && written.boundarySpec(n.written.boundary);
46
+ * // deciding that a spec containing "glass" means transparent is the viewer's judgement
47
+ * }
48
+ * ```
49
+ */
50
+ export function writtenOf(model: Model): Written {
51
+ const hit = cache.get(model);
52
+ if (hit) return hit;
53
+ const ordered = canonicalBoundaryOrder(model);
54
+ const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
55
+ const made: Written = {
56
+ boundarySpec: (b) => str(ordered[b]?.attrs["spec"]),
57
+ segSpec: (b, i) => str(ordered[b]?.segs[i]?.attrs["spec"]),
58
+ openingSpec: (b, i) => str(ordered[b]?.openings[i]?.attrs["spec"]),
59
+ boundaryAttr: (b, key) => ordered[b]?.attrs[key],
60
+ openingAttr: (b, i, key) => ordered[b]?.openings[i]?.attrs[key],
61
+ };
62
+ cache.set(model, made);
63
+ return made;
64
+ }