@miadi/ncp-story-studio 0.1.0

package/dist/schema/read.js

@@ -0,0 +1,640 @@
+// One reader for the NCP files that actually exist. Three dialects are in
+// circulation and none of them is a defect: they are what different tools
+// wrote. This module recognizes each one and returns canonical NCP plus a note
+// for every adaptation it had to make.
+//
+//   canonical       `{ schema_version, story { narratives[...] } }`, snake_case values
+//   subtxt-export   narratives beside `story`, perspectives keyed by pov,
+//                   `context` strings, Dramatica display labels, placeholder ids
+//   miadi-design    NCP container names with a design vocabulary
+//                   (`label`, `description`, `event`, `structural_function`)
+import { NCP_SCHEMA_VERSION } from './constants.js';
+import { normalizeNcpInput } from './normalize.js';
+import { canonicalDynamic, canonicalNarrativeFunction, canonicalStorybeatAppreciation, canonicalStorypointAppreciation, canonicalVector, povForContext, } from './terms.js';
+const PLACEHOLDER_ID = /^\[\[.*\]\]$/;
+function obj(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/**
+ * A collection that is not an array is read as empty and reported, rather than
+ * throwing: real exports carry objects where the schema says array.
+ */
+function arr(value, path, notes) {
+    if (Array.isArray(value))
+        return value;
+    if (value === undefined || value === null)
+        return [];
+    notes.push({ path, action: `read a ${typeof value} as an empty collection` });
+    return [];
+}
+function firstNarrative(input) {
+    const fromStory = obj(input['story'])?.['narratives'];
+    const candidates = Array.isArray(fromStory) ? fromStory : Array.isArray(input['narratives']) ? input['narratives'] : [];
+    return obj(candidates[0]);
+}
+/** Which dialect an input is written in. */
+export function detectDialect(input) {
+    const root = obj(input);
+    if (!root)
+        return 'unknown';
+    const narrative = firstNarrative(root);
+    if (!narrative)
+        return 'unknown';
+    const subtext = obj(narrative['subtext']);
+    if (!subtext)
+        return 'unknown';
+    // Perspectives keyed by point of view, or `context` strings on elements.
+    const perspectives = subtext['perspectives'];
+    if (obj(perspectives) !== undefined)
+        return 'subtxt-export';
+    const firstBeat = obj(subtext['storybeats']?.[0]);
+    if (firstBeat) {
+        if (str(firstBeat['event']) !== undefined || str(firstBeat['structural_function']) !== undefined) {
+            return 'miadi-design';
+        }
+        if (str(firstBeat['context']) !== undefined && firstBeat['perspectives'] === undefined)
+            return 'subtxt-export';
+        if (str(firstBeat['id']) !== undefined && PLACEHOLDER_ID.test(firstBeat['id']))
+            return 'subtxt-export';
+    }
+    const firstPerspective = obj(perspectives?.[0]);
+    if (firstPerspective && str(firstPerspective['label']) !== undefined)
+        return 'miadi-design';
+    const firstPlayer = obj(subtext['players']?.[0]);
+    if (firstPlayer && str(firstPlayer['structural_role']) !== undefined)
+        return 'miadi-design';
+    return 'canonical';
+}
+/** Read any recognized dialect and return canonical NCP. */
+export function readNcp(input, options) {
+    const dialect = options?.assume ?? detectDialect(input);
+    switch (dialect) {
+        case 'subtxt-export':
+            return readSubtxtExport(input, options);
+        case 'miadi-design':
+            return readMiadiDesign(input, options);
+        case 'canonical':
+        case 'unknown':
+        default: {
+            const normalized = normalizeNcpInput(input);
+            const canonicalized = canonicalizeTerms(normalized.document);
+            return {
+                document: applyOverrides(canonicalized.document, options),
+                dialect,
+                notes: [...normalized.notes, ...canonicalized.notes],
+            };
+        }
+    }
+}
+function applyOverrides(document, options) {
+    if (!options?.storyOverrides)
+        return document;
+    const overrides = Object.fromEntries(Object.entries(options.storyOverrides).filter(([, value]) => value !== undefined));
+    return { ...document, story: { ...document.story, ...overrides } };
+}
+// ---------------------------------------------------------------------------
+// subtxt-export
+// ---------------------------------------------------------------------------
+function readSubtxtExport(input, options) {
+    const notes = [];
+    const root = obj(input) ?? {};
+    const storyRaw = obj(root['story']) ?? {};
+    const narrativesRaw = Array.isArray(root['narratives'])
+        ? root['narratives']
+        : arr(storyRaw['narratives'], '$.story.narratives', notes);
+    if (Array.isArray(root['narratives'])) {
+        notes.push({ path: '$.narratives', action: 'moved top-level `narratives` under `story`' });
+    }
+    const narratives = narrativesRaw.map((narrativeRaw, index) => readSubtxtNarrative(obj(narrativeRaw) ?? {}, `$.story.narratives[${index}]`, notes));
+    const story = {
+        id: str(storyRaw['id']) ?? options?.fallbackId ?? 'story',
+        title: str(storyRaw['title']) ?? 'Untitled story',
+        genre: str(storyRaw['genre']),
+        logline: str(storyRaw['logline']),
+        created_at: str(storyRaw['created_at']),
+        narratives,
+    };
+    return {
+        document: applyOverrides({ schema_version: NCP_SCHEMA_VERSION, story }, options),
+        dialect: 'subtxt-export',
+        notes,
+    };
+}
+function readSubtxtNarrative(raw, path, notes) {
+    const subtextRaw = obj(raw['subtext']) ?? {};
+    // Perspectives arrive either as an array or as an object keyed by pov.
+    const perspectives = [];
+    const perspectivesRaw = subtextRaw['perspectives'];
+    const byContext = new Map();
+    const recordPerspective = (candidate, povHint) => {
+        const id = str(candidate['id']);
+        if (!id)
+            return;
+        const perspective = {
+            id,
+            author_structural_pov: (str(candidate['author_structural_pov']) ?? str(candidate['pov']) ?? povHint),
+            summary: str(candidate['summary']),
+            storytelling: str(candidate['storytelling']),
+            throughline: str(candidate['context']) ?? str(candidate['throughline']),
+        };
+        perspectives.push(perspective);
+        const context = str(candidate['context']);
+        if (context)
+            byContext.set(context.toLowerCase(), id);
+    };
+    if (Array.isArray(perspectivesRaw)) {
+        for (const candidate of perspectivesRaw) {
+            const holder = obj(candidate);
+            if (holder)
+                recordPerspective(holder);
+        }
+    }
+    else {
+        const keyed = obj(perspectivesRaw);
+        if (keyed) {
+            notes.push({ path: `${path}.subtext.perspectives`, action: 'flattened perspectives keyed by point of view' });
+            for (const [pov, value] of Object.entries(keyed)) {
+                const list = Array.isArray(value) ? value : [value];
+                for (const candidate of list) {
+                    const holder = obj(candidate);
+                    if (holder)
+                        recordPerspective(holder, pov);
+                }
+            }
+        }
+    }
+    const declaredIds = new Set(perspectives.map((perspective) => perspective.id));
+    const byPov = new Map();
+    for (const perspective of perspectives) {
+        const pov = perspective.author_structural_pov;
+        if (pov && !byPov.has(pov))
+            byPov.set(pov, perspective.id);
+    }
+    // These exports carry a fresh random `perspective_id` on every element, and
+    // none of them resolves. The real link is the `context` label, which names a
+    // throughline and therefore a point of view.
+    const resolveContext = (context) => {
+        if (!context)
+            return undefined;
+        const direct = byContext.get(context.toLowerCase());
+        if (direct)
+            return direct;
+        const pov = povForContext(context);
+        return pov ? byPov.get(pov) : undefined;
+    };
+    const refsFor = (holder, at) => {
+        const existing = holder['perspectives'];
+        const declaredRefs = [];
+        if (Array.isArray(existing)) {
+            for (const entry of existing) {
+                const id = str(obj(entry)?.['perspective_id']);
+                if (id)
+                    declaredRefs.push(id);
+            }
+        }
+        else {
+            const single = obj(existing);
+            const id = single ? str(single['perspective_id']) : undefined;
+            if (id)
+                declaredRefs.push(id);
+        }
+        const resolvable = declaredRefs.filter((id) => declaredIds.has(id));
+        if (resolvable.length > 0) {
+            if (resolvable.length !== declaredRefs.length) {
+                notes.push({ path: `${at}.perspectives`, action: 'dropped references to undeclared perspectives' });
+            }
+            return resolvable.map((id) => ({ perspective_id: id }));
+        }
+        const context = str(holder['context']);
+        const resolved = resolveContext(context);
+        if (resolved) {
+            if (declaredRefs.length > 0) {
+                notes.push({
+                    path: `${at}.perspectives`,
+                    action: `reference \`${declaredRefs[0]}\` matches no declared perspective; used \`context\` \`${context}\` instead`,
+                });
+            }
+            else {
+                notes.push({ path: `${at}.perspectives`, action: `resolved \`context\` to perspective \`${resolved}\`` });
+            }
+            return [{ perspective_id: resolved }];
+        }
+        if (declaredRefs.length > 0 || context) {
+            notes.push({
+                path: `${at}.perspectives`,
+                action: context
+                    ? `left unreferenced: \`context\` \`${context}\` names no declared perspective`
+                    : 'left unreferenced: the perspective id matches no declared perspective',
+            });
+        }
+        return undefined;
+    };
+    const players = arr(subtextRaw['players'], `${path}.subtext.players`, notes).map((candidate, index) => {
+        const holder = obj(candidate) ?? {};
+        const at = `${path}.subtext.players[${index}]`;
+        return {
+            id: str(holder['id']) ?? `player-${index + 1}`,
+            name: str(holder['name']) ?? `Player ${index + 1}`,
+            role: str(holder['role']) ?? '',
+            visual: str(holder['visual']),
+            audio: str(holder['audio']),
+            summary: str(holder['summary']) ?? str(holder['bio']),
+            storytelling: str(holder['storytelling']),
+            perspectives: refsFor(holder, at),
+        };
+    });
+    const dynamics = arr(subtextRaw['dynamics'], `${path}.subtext.dynamics`, notes).map((candidate, index) => {
+        const holder = obj(candidate) ?? {};
+        const at = `${path}.subtext.dynamics[${index}]`;
+        const rawDynamic = str(holder['dynamic']) ?? '';
+        const rawVector = str(holder['vector']) ?? '';
+        const dynamic = canonicalDynamic(rawDynamic);
+        const vector = canonicalVector(rawVector);
+        if (rawDynamic && !dynamic) {
+            notes.push({ path: `${at}.dynamic`, action: `declared \`${rawDynamic}\` in \`custom_dynamic\`` });
+        }
+        if (rawVector && !vector) {
+            notes.push({ path: `${at}.vector`, action: `declared \`${rawVector}\` in \`custom_vector\`` });
+        }
+        return {
+            id: str(holder['id']) ?? `dynamic-${index + 1}`,
+            dynamic,
+            vector,
+            ...(dynamic || !rawDynamic ? {} : { custom_dynamic: rawDynamic }),
+            ...(vector || !rawVector ? {} : { custom_vector: rawVector }),
+            summary: str(holder['summary']),
+            storytelling: str(holder['storytelling']),
+        };
+    });
+    const storypoints = arr(subtextRaw['storypoints'], `${path}.subtext.storypoints`, notes).map((candidate, index) => {
+        const holder = obj(candidate) ?? {};
+        const at = `${path}.subtext.storypoints[${index}]`;
+        const rawAppreciation = str(holder['appreciation']) ?? '';
+        const rawFunction = str(holder['narrative_function']) ?? '';
+        const appreciation = canonicalStorypointAppreciation(rawAppreciation);
+        const narrativeFunction = canonicalNarrativeFunction(rawFunction, 'storypoint');
+        if (rawAppreciation && !appreciation) {
+            notes.push({ path: `${at}.appreciation`, action: `declared \`${rawAppreciation}\` as a custom appreciation` });
+        }
+        if (rawFunction && !narrativeFunction) {
+            notes.push({ path: `${at}.narrative_function`, action: `declared \`${rawFunction}\` as a custom function` });
+        }
+        return {
+            id: str(holder['id']) ?? `storypoint-${index + 1}`,
+            appreciation: appreciation ?? 'domain',
+            narrative_function: narrativeFunction ?? 'universe',
+            ...(appreciation || !rawAppreciation ? {} : { custom_appreciation: rawAppreciation }),
+            ...(narrativeFunction || !rawFunction ? {} : { custom_narrative_function: rawFunction }),
+            illustration: str(holder['illustration']),
+            summary: str(holder['summary']),
+            storytelling: str(holder['storytelling']),
+            perspectives: refsFor(holder, at),
+        };
+    });
+    // Placeholder ids and null sequences are common in these exports. A beat's
+    // sequence numbers a series — one throughline's signposts, or its
+    // progressions — so an unnumbered beat is numbered after the last number that
+    // series already uses, never over it.
+    const beatsRaw = arr(subtextRaw['storybeats'], `${path}.subtext.storybeats`, notes);
+    const seriesKeyOf = (holder) => {
+        const context = (str(holder['context']) ?? 'unscoped').toLowerCase();
+        const appreciation = canonicalStorybeatAppreciation(str(holder['appreciation']) ?? '') ?? 'event';
+        return `${context}|${appreciation}`;
+    };
+    const seriesHighWater = new Map();
+    for (const candidate of beatsRaw) {
+        const holder = obj(candidate);
+        if (!holder)
+            continue;
+        const sequence = holder['sequence'];
+        if (typeof sequence !== 'number')
+            continue;
+        const key = seriesKeyOf(holder);
+        seriesHighWater.set(key, Math.max(seriesHighWater.get(key) ?? 0, sequence));
+    }
+    const storybeats = beatsRaw.map((candidate, index) => {
+        const holder = obj(candidate) ?? {};
+        const at = `${path}.subtext.storybeats[${index}]`;
+        const seriesKey = seriesKeyOf(holder);
+        const rawId = str(holder['id']);
+        let id = rawId;
+        if (!id || PLACEHOLDER_ID.test(id)) {
+            id = `beat-${index + 1}`;
+            notes.push({ path: `${at}.id`, action: `replaced a placeholder id with \`${id}\`` });
+        }
+        let sequence = typeof holder['sequence'] === 'number' ? holder['sequence'] : undefined;
+        if (sequence === undefined) {
+            sequence = (seriesHighWater.get(seriesKey) ?? 0) + 1;
+            seriesHighWater.set(seriesKey, sequence);
+            notes.push({ path: `${at}.sequence`, action: `numbered ${sequence}, after the \`${seriesKey}\` series` });
+        }
+        const rawAppreciation = str(holder['appreciation']) ?? '';
+        const appreciation = canonicalStorybeatAppreciation(rawAppreciation);
+        if (rawAppreciation && !appreciation) {
+            notes.push({ path: `${at}.appreciation`, action: `read \`${rawAppreciation}\` as \`event\`` });
+        }
+        const rawFunction = str(holder['narrative_function']) ?? '';
+        const narrativeFunction = canonicalNarrativeFunction(rawFunction, 'storybeat');
+        if (rawFunction && !narrativeFunction) {
+            notes.push({ path: `${at}.narrative_function`, action: `declared \`${rawFunction}\` as a custom function` });
+        }
+        return {
+            id,
+            appreciation: (appreciation ?? 'event'),
+            sequence,
+            narrative_function: narrativeFunction ?? 'past',
+            ...(narrativeFunction || !rawFunction ? {} : { custom_narrative_function: rawFunction }),
+            illustration: str(holder['illustration']),
+            summary: str(holder['summary']),
+            storytelling: str(holder['storytelling']),
+            tones: obj(holder['tones']),
+            perspectives: refsFor(holder, at),
+        };
+    });
+    const storytellingRaw = obj(raw['storytelling']) ?? {};
+    return {
+        id: str(raw['id']) ?? 'narrative',
+        title: str(raw['title']) ?? 'Untitled narrative',
+        subtext: { perspectives, players, dynamics, storypoints, storybeats },
+        storytelling: {
+            overviews: arr(storytellingRaw['overviews'], `${path}.storytelling.overviews`, notes).map((candidate, index) => {
+                const holder = obj(candidate) ?? {};
+                return {
+                    id: str(holder['id']) ?? `overview-${index + 1}`,
+                    summary: str(holder['summary']) ?? str(holder['title']),
+                    storytelling: str(holder['storytelling']) ?? str(holder['description']),
+                };
+            }),
+            moments: arr(storytellingRaw['moments'], `${path}.storytelling.moments`, notes).map((candidate, index) => readMoment(obj(candidate) ?? {}, index)),
+        },
+    };
+}
+function readMoment(holder, index) {
+    const beatRefs = holder['storybeats'] ?? holder['beat_references'];
+    const storybeats = Array.isArray(beatRefs)
+        ? beatRefs.map((entry, refIndex) => {
+            if (typeof entry === 'string')
+                return { sequence: refIndex + 1, storybeat_id: entry };
+            const refHolder = obj(entry) ?? {};
+            return {
+                sequence: typeof refHolder['sequence'] === 'number' ? refHolder['sequence'] : refIndex + 1,
+                storybeat_id: String(refHolder['storybeat_id'] ?? ''),
+            };
+        })
+        : undefined;
+    return {
+        id: str(holder['id']) ?? `moment-${index + 1}`,
+        summary: str(holder['summary']) ?? str(holder['title']),
+        synopsis: str(holder['synopsis']) ?? str(holder['scene_summary']),
+        setting: str(holder['setting']),
+        timing: str(holder['timing']),
+        imperatives: str(holder['imperatives']),
+        fabric: Array.isArray(holder['fabric']) ? holder['fabric'] : undefined,
+        audience_experiential_pov: str(holder['audience_experiential_pov']),
+        storybeats,
+    };
+}
+// ---------------------------------------------------------------------------
+// miadi-design
+// ---------------------------------------------------------------------------
+/**
+ * The mapping the prototype's `adaptCatalystStory` established, kept as the
+ * contract: design fields land on the NCP field that carries the same load, and
+ * nothing is invented for a field the source does not have.
+ */
+function readMiadiDesign(input, options) {
+    const notes = [];
+    const root = obj(input) ?? {};
+    const storyRaw = obj(root['story']) ?? root;
+    const narrativesRaw = arr(storyRaw['narratives'], '$.story.narratives', notes);
+    const narratives = narrativesRaw.map((narrativeRaw, index) => {
+        const raw = obj(narrativeRaw) ?? {};
+        const path = `$.story.narratives[${index}]`;
+        const subtextRaw = obj(raw['subtext']) ?? {};
+        const perspectives = arr(subtextRaw['perspectives'], `${path}.subtext.perspectives`, notes).map((candidate, i) => {
+            const holder = obj(candidate) ?? {};
+            return {
+                id: str(holder['id']) ?? `perspective-${i + 1}`,
+                summary: str(holder['label']) ?? str(holder['summary']),
+                storytelling: str(holder['description']) ?? str(holder['storytelling']),
+                throughline: str(holder['thematic_question']),
+            };
+        });
+        if (perspectives.length > 0) {
+            notes.push({
+                path: `${path}.subtext.perspectives`,
+                action: 'read `label`/`description` as summary/storytelling; left `author_structural_pov` unset',
+            });
+        }
+        const players = arr(subtextRaw['players'], `${path}.subtext.players`, notes).map((candidate, i) => {
+            const holder = obj(candidate) ?? {};
+            return {
+                id: str(holder['id']) ?? `player-${i + 1}`,
+                name: str(holder['name']) ?? `Player ${i + 1}`,
+                role: str(holder['structural_role']) ?? str(holder['role']) ?? '',
+                summary: str(holder['function']) ?? str(holder['summary']),
+                storytelling: str(holder['thematic_representation']) ?? str(holder['arc']) ?? str(holder['storytelling']),
+                motivations: str(holder['wound'])
+                    ? [{ narrative_function: 'wound', illustration: holder['wound'] }]
+                    : undefined,
+            };
+        });
+        const dynamics = arr(subtextRaw['dynamics'], `${path}.subtext.dynamics`, notes).map((candidate, i) => {
+            const holder = obj(candidate) ?? {};
+            const label = str(holder['label']) ?? str(holder['dynamic']) ?? '';
+            const mapped = canonicalDynamic(label);
+            const rawVector = str(holder['vector']) ?? '';
+            const vector = canonicalVector(rawVector);
+            if (label && !mapped) {
+                notes.push({
+                    path: `${path}.subtext.dynamics[${i}]`,
+                    action: `\`${label}\` is not a Dramatica dynamic; declared it in \`custom_dynamic\``,
+                });
+            }
+            return {
+                id: str(holder['id']) ?? `dynamic-${i + 1}`,
+                dynamic: mapped,
+                vector,
+                ...(mapped || !label ? {} : { custom_dynamic: label }),
+                ...(vector || !rawVector ? {} : { custom_vector: rawVector }),
+                summary: str(holder['description']) ?? str(holder['summary']),
+                storytelling: str(holder['manifestation']) ?? str(holder['thematic_significance']),
+            };
+        });
+        const storypoints = arr(subtextRaw['storypoints'], `${path}.subtext.storypoints`, notes).map((candidate, i) => {
+            const holder = obj(candidate) ?? {};
+            const label = str(holder['label']) ?? '';
+            const mapped = canonicalStorypointAppreciation(label.split(':')[0] ?? '');
+            return {
+                id: str(holder['id']) ?? `storypoint-${i + 1}`,
+                appreciation: mapped ?? 'domain',
+                narrative_function: 'universe',
+                ...(mapped || !label.split(':')[0]?.trim() ? {} : { custom_appreciation: label.split(':')[0].trim() }),
+                summary: label || str(holder['summary']),
+                storytelling: str(holder['description']) ?? str(holder['storytelling']),
+            };
+        });
+        if (storypoints.length > 0) {
+            notes.push({
+                path: `${path}.subtext.storypoints`,
+                action: 'declared design labels as custom appreciations; canonical narrative functions are unset',
+            });
+        }
+        const storybeats = arr(subtextRaw['storybeats'], `${path}.subtext.storybeats`, notes).map((candidate, i) => {
+            const holder = obj(candidate) ?? {};
+            const event = str(holder['event']);
+            const structural = str(holder['structural_function']);
+            const emotional = str(holder['emotional_weight']);
+            const appreciation = canonicalStorybeatAppreciation(structural ?? '') ?? 'event';
+            const storytelling = emotional && event ? `${event}\n\n[Emotional weight: ${emotional}]` : (event ?? undefined);
+            return {
+                id: str(holder['id']) ?? `beat-${i + 1}`,
+                appreciation: appreciation,
+                sequence: typeof holder['sequence'] === 'number' ? holder['sequence'] : i + 1,
+                narrative_function: canonicalNarrativeFunction(structural ?? '', 'storybeat') ?? 'past',
+                ...(structural && !canonicalNarrativeFunction(structural, 'storybeat')
+                    ? { custom_narrative_function: structural }
+                    : {}),
+                illustration: event,
+                summary: structural ?? (event ? `${event.slice(0, 60)}…` : undefined),
+                storytelling,
+                tones: obj(holder['tones']),
+            };
+        });
+        if (storybeats.length > 0) {
+            notes.push({
+                path: `${path}.subtext.storybeats`,
+                action: 'read `event` as illustration, `structural_function` as summary, `emotional_weight` into storytelling',
+            });
+        }
+        const storytellingRaw = obj(raw['storytelling']) ?? {};
+        return {
+            id: str(raw['id']) ?? 'narrative',
+            title: str(raw['title']) ?? 'Untitled narrative',
+            subtext: { perspectives, players, dynamics, storypoints, storybeats },
+            storytelling: {
+                overviews: arr(storytellingRaw['overviews'], `${path}.storytelling.overviews`, notes).map((candidate, i) => {
+                    const holder = obj(candidate) ?? {};
+                    return {
+                        id: str(holder['id']) ?? `overview-${i + 1}`,
+                        summary: str(holder['title']) ?? str(holder['summary']),
+                        storytelling: str(holder['description']) ?? str(holder['storytelling']),
+                    };
+                }),
+                moments: arr(storytellingRaw['moments'], `${path}.storytelling.moments`, notes).map((candidate, i) => readMoment(obj(candidate) ?? {}, i)),
+            },
+        };
+    });
+    const story = {
+        id: str(storyRaw['id']) ?? options?.fallbackId ?? 'story',
+        title: str(storyRaw['title']) ?? 'Untitled story',
+        genre: str(storyRaw['genre']),
+        logline: str(storyRaw['logline']),
+        created_at: str(storyRaw['created_at']) ?? str(storyRaw['date_written']),
+        narratives,
+    };
+    return {
+        document: applyOverrides({ schema_version: NCP_SCHEMA_VERSION, story }, options),
+        dialect: 'miadi-design',
+        notes,
+    };
+}
+// ---------------------------------------------------------------------------
+// canonical dialect: display labels to identifiers
+// ---------------------------------------------------------------------------
+/**
+ * A canonical-layout document can still carry Dramatica display labels where
+ * the schema declares identifiers — `example-story.json` does. This maps them
+ * and declares whatever it cannot map, so a consumer never has to guess whether
+ * `"Success"` and `"success"` are the same value.
+ */
+export function canonicalizeTerms(document) {
+    const notes = [];
+    const narratives = document.story.narratives.map((narrative, narrativeIndex) => {
+        const path = `$.story.narratives[${narrativeIndex}]`;
+        const dynamics = narrative.subtext.dynamics.map((dynamic, index) => {
+            const at = `${path}.subtext.dynamics[${index}]`;
+            const rawDynamic = typeof dynamic.dynamic === 'string' ? dynamic.dynamic : '';
+            const rawVector = typeof dynamic.vector === 'string' ? dynamic.vector : '';
+            const mappedDynamic = rawDynamic ? canonicalDynamic(rawDynamic) : undefined;
+            const mappedVector = rawVector ? canonicalVector(rawVector) : undefined;
+            if (rawDynamic && mappedDynamic && mappedDynamic !== rawDynamic) {
+                notes.push({ path: `${at}.dynamic`, action: `read \`${rawDynamic}\` as \`${mappedDynamic}\`` });
+            }
+            if (rawVector && mappedVector && mappedVector !== rawVector) {
+                notes.push({ path: `${at}.vector`, action: `read \`${rawVector}\` as \`${mappedVector}\`` });
+            }
+            if (rawDynamic && !mappedDynamic) {
+                notes.push({ path: `${at}.dynamic`, action: `declared \`${rawDynamic}\` in \`custom_dynamic\`` });
+            }
+            if (rawVector && !mappedVector) {
+                notes.push({ path: `${at}.vector`, action: `declared \`${rawVector}\` in \`custom_vector\`` });
+            }
+            const customDynamic = mappedDynamic ? dynamic.custom_dynamic : rawDynamic || dynamic.custom_dynamic;
+            const customVector = mappedVector ? dynamic.custom_vector : rawVector || dynamic.custom_vector;
+            return {
+                ...dynamic,
+                ...(mappedDynamic === undefined ? {} : { dynamic: mappedDynamic }),
+                ...(mappedVector === undefined ? {} : { vector: mappedVector }),
+                ...(customDynamic === undefined ? {} : { custom_dynamic: customDynamic }),
+                ...(customVector === undefined ? {} : { custom_vector: customVector }),
+            };
+        });
+        const storypoints = narrative.subtext.storypoints.map((storypoint, index) => {
+            const at = `${path}.subtext.storypoints[${index}]`;
+            const rawAppreciation = typeof storypoint.appreciation === 'string' ? storypoint.appreciation : '';
+            const rawFunction = typeof storypoint.narrative_function === 'string' ? storypoint.narrative_function : '';
+            const appreciation = rawAppreciation ? canonicalStorypointAppreciation(rawAppreciation) : undefined;
+            const narrativeFunction = rawFunction ? canonicalNarrativeFunction(rawFunction, 'storypoint') : undefined;
+            if (rawAppreciation && appreciation && appreciation !== rawAppreciation) {
+                notes.push({ path: `${at}.appreciation`, action: `read \`${rawAppreciation}\` as \`${appreciation}\`` });
+            }
+            if (rawFunction && narrativeFunction && narrativeFunction !== rawFunction) {
+                notes.push({ path: `${at}.narrative_function`, action: `read \`${rawFunction}\` as \`${narrativeFunction}\`` });
+            }
+            const customAppreciation = appreciation
+                ? storypoint.custom_appreciation
+                : rawAppreciation || storypoint.custom_appreciation;
+            const customFunction = narrativeFunction
+                ? storypoint.custom_narrative_function
+                : rawFunction || storypoint.custom_narrative_function;
+            return {
+                ...storypoint,
+                appreciation: appreciation ?? storypoint.appreciation,
+                narrative_function: narrativeFunction ?? storypoint.narrative_function,
+                ...(customAppreciation === undefined ? {} : { custom_appreciation: customAppreciation }),
+                ...(customFunction === undefined ? {} : { custom_narrative_function: customFunction }),
+            };
+        });
+        const storybeats = narrative.subtext.storybeats.map((beat, index) => {
+            const at = `${path}.subtext.storybeats[${index}]`;
+            const rawAppreciation = typeof beat.appreciation === 'string' ? beat.appreciation : '';
+            const rawFunction = typeof beat.narrative_function === 'string' ? beat.narrative_function : '';
+            const appreciation = rawAppreciation ? canonicalStorybeatAppreciation(rawAppreciation) : undefined;
+            const narrativeFunction = rawFunction ? canonicalNarrativeFunction(rawFunction, 'storybeat') : undefined;
+            if (rawAppreciation && appreciation && appreciation !== rawAppreciation) {
+                notes.push({ path: `${at}.appreciation`, action: `read \`${rawAppreciation}\` as \`${appreciation}\`` });
+            }
+            if (rawFunction && narrativeFunction && narrativeFunction !== rawFunction) {
+                notes.push({ path: `${at}.narrative_function`, action: `read \`${rawFunction}\` as \`${narrativeFunction}\`` });
+            }
+            const customFunction = narrativeFunction
+                ? beat.custom_narrative_function
+                : rawFunction || beat.custom_narrative_function;
+            return {
+                ...beat,
+                appreciation: (appreciation ?? beat.appreciation),
+                narrative_function: narrativeFunction ?? beat.narrative_function,
+                ...(customFunction === undefined ? {} : { custom_narrative_function: customFunction }),
+            };
+        });
+        return { ...narrative, subtext: { ...narrative.subtext, dynamics, storypoints, storybeats } };
+    });
+    return { document: { ...document, story: { ...document.story, narratives } }, notes };
+}
+//# sourceMappingURL=read.js.map