@mcptoolshop/style-dataset-lab 3.1.0 → 3.3.0

package/lib/canon-build/emitters/monster.js

@@ -0,0 +1,131 @@
+/**
+ * Monster emitter (D5: monster.schema.json).
+ *
+ * Caption: trigger + " style, a " + species_tag + " creature, " + signature_features[0..2]
+ * Prompt positive: visual cue + anatomy + lineage hint + scale; human_element suppressed unless species_tag="hybrid"
+ * Prompt negative: forbidden_inputs + synthetic human-guard when human_element is null
+ * Context sections: Identity, Anatomy, Combat intent, Forbidden, Sources
+ */
+
+import { contextFrontmatter, renderKeyValueSection, renderSection, renderNegativeBase } from './base.js';
+
+const SCHEMA_KIND = 'monster';
+
+export function emitMonster(entry, ctx) {
+  const fm = entry.frontmatter;
+  return {
+    schemaKind: SCHEMA_KIND,
+    caption: buildCaption(fm, ctx),
+    prompt: buildPromptTemplate(fm),
+    context: buildContext(entry, ctx),
+  };
+}
+
+function buildCaption(fm, ctx) {
+  const segments = [];
+  if (ctx.trigger) segments.push(`${ctx.trigger} style`);
+
+  const species = fm.species_tag || 'creature';
+  segments.push(`a ${species} creature`);
+
+  const features = Array.isArray(fm.signature_features) ? fm.signature_features.slice(0, 2) : [];
+  if (features.length) {
+    segments.push(features.join(', '));
+  }
+
+  const notable = fm.anatomy_descriptor?.notable;
+  if (Array.isArray(notable) && notable.length) {
+    segments.push(notable[0]);
+  }
+
+  return segments.join(', ');
+}
+
+function buildPromptTemplate(fm) {
+  const lines = [];
+  lines.push(`{# auto-generated canon-build prompt template — do not hand-edit #}`);
+  lines.push(`{{ trigger }} style, a ${fm.species_tag || 'creature'}, ${formatFeatures(fm.signature_features)}.`);
+
+  const anatomy = formatAnatomy(fm.anatomy_descriptor);
+  if (anatomy) lines.push(anatomy);
+
+  if (fm.lineage_reference && fm.lineage_reference !== 'none') {
+    lines.push(`{# lineage #} ${fm.lineage_reference} descent`);
+  }
+  if (fm.scale_indicator) {
+    lines.push(`{# scale #} ${fm.scale_indicator}`);
+  }
+
+  // Human-element handling — suppression is a hard guard against contamination.
+  if (fm.species_tag === 'hybrid' && fm.human_element) {
+    lines.push(`{# hybrid override #} human portion: ${fm.human_element.scope}`);
+  }
+
+  lines.push('---');
+  lines.push(`{{ negative_base }}`);
+  if (!fm.human_element) {
+    lines.push(', human features, human face, human torso');
+  }
+  return lines.join('\n') + '\n';
+}
+
+function buildContext(entry, ctx) {
+  const fm = entry.frontmatter;
+  const out = [];
+  out.push(contextFrontmatter({
+    entityId: fm.id,
+    schemaKind: SCHEMA_KIND,
+    generatedFrom: ctx.generatedFrom,
+    entryHash: ctx.entryHash,
+  }));
+
+  out.push(`# ${titleFromId(fm.id)}\n`);
+
+  out.push(renderKeyValueSection('Identity', [
+    ['species_tag', fm.species_tag],
+    ['lineage_reference', fm.lineage_reference],
+    ['lineage_detail', fm.lineage_detail],
+    ['scale_indicator', fm.scale_indicator],
+  ]));
+
+  out.push(renderSection('Anatomy', fm.anatomy_descriptor || null));
+
+  if (fm.human_element) {
+    out.push(renderSection('Human element', fm.human_element));
+  }
+
+  out.push(renderSection('Combat intent', fm.signature_features || null));
+  out.push(renderSection('Forbidden', fm.forbidden_inputs || null));
+  out.push(renderSection('Sources', fm.sources || null));
+
+  // Canon prose body feeds context exclusively.
+  if (entry.body && entry.body.trim()) {
+    out.push(`## Notes\n${entry.body.trim()}\n`);
+  }
+
+  return out.join('');
+}
+
+function formatFeatures(features) {
+  if (!Array.isArray(features) || features.length === 0) return 'creature silhouette';
+  return features.join(', ');
+}
+
+function formatAnatomy(desc) {
+  if (!desc || typeof desc !== 'object') return '';
+  const parts = [];
+  if (typeof desc.heads === 'number') parts.push(`${desc.heads} head${desc.heads === 1 ? '' : 's'}`);
+  if (typeof desc.limbs === 'number') parts.push(`${desc.limbs} limb${desc.limbs === 1 ? '' : 's'}`);
+  if (typeof desc.wings === 'number' && desc.wings > 0) parts.push(`${desc.wings} wing${desc.wings === 1 ? '' : 's'}`);
+  if (typeof desc.tails === 'number' && desc.tails > 0) parts.push(`${desc.tails} tail${desc.tails === 1 ? '' : 's'}`);
+  if (Array.isArray(desc.notable) && desc.notable.length) parts.push(...desc.notable);
+  if (!parts.length) return '';
+  return `{# anatomy #} ${parts.join(', ')}`;
+}
+
+function titleFromId(id) {
+  if (!id) return 'Untitled';
+  return id.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
+export { buildCaption as _buildCaption, buildPromptTemplate as _buildPromptTemplate, buildContext as _buildContext };

package/lib/canon-build/emitters/relic.js

@@ -0,0 +1,142 @@
+/**
+ * Relic emitter (D5: relic.schema.json).
+ *
+ * Caption: trigger + " style, a " + relic_type + ", " + silhouette_cue + ", " + materials.join(" and ")
+ * Prompt positive: silhouette_cue + signature_markings + materials + scale + wear_level + attachment_to_wearer + palette + signature_features
+ * Prompt negative: forbidden_inputs
+ * Context sections: Identity, Role & Significance, Powers, Ownership Chain, Associations, Mechanical (optional), Forbidden, Sources
+ */
+
+import { contextFrontmatter, renderKeyValueSection, renderSection } from './base.js';
+
+const SCHEMA_KIND = 'relic';
+
+export function emitRelic(entry, ctx) {
+  const fm = entry.frontmatter;
+  return {
+    schemaKind: SCHEMA_KIND,
+    caption: buildCaption(fm, ctx),
+    prompt: buildPromptTemplate(fm),
+    context: buildContext(entry, ctx),
+  };
+}
+
+function buildCaption(fm, ctx) {
+  const v = fm.visual || {};
+  const segments = [];
+  if (ctx.trigger) segments.push(`${ctx.trigger} style`);
+
+  const head = fm.relic_type ? `a ${fm.relic_type}` : 'a relic';
+  segments.push(head);
+
+  if (v.silhouette_cue) segments.push(v.silhouette_cue);
+
+  if (Array.isArray(fm.materials) && fm.materials.length) {
+    segments.push(fm.materials.join(' and '));
+  }
+
+  return segments.join(', ');
+}
+
+function buildPromptTemplate(fm) {
+  const v = fm.visual || {};
+  const lines = [];
+  lines.push(`{# auto-generated canon-build prompt template — do not hand-edit #}`);
+  lines.push(`{{ trigger }} style, a ${fm.relic_type || 'relic'}, ${v.silhouette_cue || ''}.`);
+
+  if (Array.isArray(v.signature_markings) && v.signature_markings.length) {
+    lines.push(`{# markings #} ${v.signature_markings.join(', ')}`);
+  }
+  if (Array.isArray(fm.materials) && fm.materials.length) {
+    lines.push(`{# materials #} ${fm.materials.join(', ')}`);
+  }
+  if (v.scale) lines.push(`{# scale #} ${v.scale}`);
+  if (v.wear_level) lines.push(`{# wear #} ${v.wear_level}`);
+  if (v.attachment_to_wearer) {
+    lines.push(`{# attachment #} {% if character_trigger %}${v.attachment_to_wearer}{% endif %}`);
+  }
+  if (Array.isArray(v.palette) && v.palette.length) {
+    lines.push(`{# palette #} ${v.palette.join(' ')}`);
+  }
+  if (Array.isArray(fm.signature_features) && fm.signature_features.length) {
+    lines.push(`{# signature #} ${fm.signature_features.join(', ')}`);
+  }
+
+  lines.push('---');
+  lines.push(`{{ negative_base }}`);
+  return lines.join('\n') + '\n';
+}
+
+function buildContext(entry, ctx) {
+  const fm = entry.frontmatter;
+  const n = fm.narrative || {};
+  const m = fm.mechanical;
+  const out = [];
+
+  out.push(contextFrontmatter({
+    entityId: fm.id,
+    schemaKind: SCHEMA_KIND,
+    generatedFrom: ctx.generatedFrom,
+    entryHash: ctx.entryHash,
+  }));
+  out.push(`# ${titleFromId(fm.id)}\n`);
+
+  out.push(renderKeyValueSection('Identity', [
+    ['relic_type', fm.relic_type],
+    ['origin', fm.origin],
+    ['current_status', fm.current_status],
+  ]));
+
+  out.push(renderKeyValueSection('Role & Significance', [
+    ['role', n.role],
+    ['mythic_significance', n.mythic_significance],
+  ]));
+
+  if (Array.isArray(fm.powers) && fm.powers.length) {
+    const bullets = fm.powers.map((p) => {
+      const conditions = p.conditions ? ` — ${p.conditions}` : '';
+      const limits = p.limits ? ` — limits: ${p.limits}` : '';
+      return `${p.effect}${conditions}${limits}`;
+    });
+    out.push(renderSection('Powers', bullets));
+  }
+
+  if (Array.isArray(fm.ownership_chain) && fm.ownership_chain.length) {
+    const bullets = fm.ownership_chain.map((o) => {
+      const from = o.acquired_from ? ` from ${o.acquired_from}` : '';
+      const note = o.note ? ` (${o.note})` : '';
+      return `${o.era}: ${o.owner_id} via ${o.acquired_by}${from}${note}`;
+    });
+    out.push(renderSection('Ownership Chain', bullets));
+  }
+
+  out.push(renderKeyValueSection('Associations', [
+    ['associated_myths', n.associated_myths],
+    ['counterparts', n.counterparts],
+  ]));
+
+  if (m && typeof m === 'object' && Object.values(m).some((v) => v != null)) {
+    out.push(renderKeyValueSection('Mechanical', [
+      ['unlock_trigger', m.unlock_trigger],
+      ['grants', m.grants],
+      ['drawbacks', m.drawbacks],
+      ['slot', m.slot],
+    ]));
+  }
+
+  out.push(renderSection('Forbidden', fm.forbidden_inputs || null));
+  out.push(renderSection('Sources', fm.sources || null));
+
+  if (entry.body && entry.body.trim()) {
+    out.push(`## Notes\n${entry.body.trim()}\n`);
+  }
+
+  return out.join('');
+}
+
+function titleFromId(id) {
+  if (!id) return 'Untitled';
+  return id.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
+export { buildCaption as _buildCaption, buildPromptTemplate as _buildPromptTemplate, buildContext as _buildContext };

package/lib/canon-build/emitters/ship.js

@@ -0,0 +1,154 @@
+/**
+ * Ship emitter (Star Freight D5).
+ *
+ * silhouette_cue is the heaviest trainable leverage for ships — the player
+ * sees them at multiple scales (nav chart, exterior establishing, dock
+ * approach, interior cockpit). The emitter lifts it to the caption and
+ * foregrounds it in the prompt template.
+ *
+ * Caption: trigger + " style, a " + ship_class + " ship, " +
+ *          silhouette_cue + ", " + material_dominant
+ * Prompt positive: silhouette_cue + tonnage_class + hull_repair_history +
+ *                  symmetry + material_dominant + hull_markings +
+ *                  scale_cue_object + cockpit_style + engine_signature +
+ *                  palette + signature_features
+ * Prompt negative: forbidden_inputs
+ */
+
+import { contextFrontmatter, renderKeyValueSection, renderSection } from './base.js';
+
+const SCHEMA_KIND = 'ship';
+
+export function emitShip(entry, ctx) {
+  const fm = entry.frontmatter;
+  return {
+    schemaKind: SCHEMA_KIND,
+    caption: buildCaption(fm, ctx),
+    prompt: buildPromptTemplate(fm),
+    context: buildContext(entry, ctx),
+  };
+}
+
+function buildCaption(fm, ctx) {
+  const v = fm.visual || {};
+  const segments = [];
+  if (ctx.trigger) segments.push(`${ctx.trigger} style`);
+
+  const cls = fm.ship_class || 'ship';
+  segments.push(`a ${cls} ship`);
+
+  if (v.silhouette_cue) segments.push(v.silhouette_cue);
+  if (v.material_dominant) segments.push(v.material_dominant);
+
+  return segments.join(', ');
+}
+
+function buildPromptTemplate(fm) {
+  const v = fm.visual || {};
+  const lines = [];
+  lines.push(`{# auto-generated canon-build prompt template — do not hand-edit #}`);
+  lines.push(`{{ trigger }} style, a ${fm.ship_class || 'ship'}, ${v.silhouette_cue || ''}.`);
+
+  if (fm.tonnage_class) lines.push(`{# tonnage #} ${fm.tonnage_class}`);
+  if (v.hull_repair_history) lines.push(`{# hull #} ${v.hull_repair_history}`);
+  if (v.symmetry) lines.push(`{# symmetry #} ${v.symmetry}`);
+  if (v.material_dominant) lines.push(`{# material #} ${v.material_dominant}`);
+  if (Array.isArray(v.hull_markings) && v.hull_markings.length) {
+    lines.push(`{# markings #} ${v.hull_markings.join(', ')}`);
+  }
+  if (v.scale_cue_object) lines.push(`{# scale #} ${v.scale_cue_object}`);
+  if (v.cockpit_style) lines.push(`{# cockpit #} ${v.cockpit_style}`);
+  if (v.engine_signature) lines.push(`{# engine #} ${v.engine_signature}`);
+  if (Array.isArray(v.palette) && v.palette.length) {
+    lines.push(`{# palette #} ${v.palette.join(' ')}`);
+  }
+  if (Array.isArray(fm.signature_features) && fm.signature_features.length) {
+    lines.push(`{# signature #} ${fm.signature_features.join(', ')}`);
+  }
+
+  lines.push('---');
+  lines.push(`{{ negative_base }}`);
+  return lines.join('\n') + '\n';
+}
+
+function buildContext(entry, ctx) {
+  const fm = entry.frontmatter;
+  const n = fm.narrative || {};
+  const m = fm.mechanical;
+  const v = fm.visual || {};
+  const out = [];
+
+  out.push(contextFrontmatter({
+    entityId: fm.id,
+    schemaKind: SCHEMA_KIND,
+    generatedFrom: ctx.generatedFrom,
+    entryHash: ctx.entryHash,
+  }));
+  out.push(`# ${titleFromId(fm.id)}\n`);
+
+  out.push(renderKeyValueSection('Identity', [
+    ['ship_class', fm.ship_class],
+    ['tonnage_class', fm.tonnage_class],
+    ['faction_of_origin', fm.faction_of_origin],
+    ['current_operator', fm.current_operator],
+  ]));
+
+  out.push(renderKeyValueSection('Visual', [
+    ['silhouette_cue', v.silhouette_cue],
+    ['palette', v.palette],
+    ['hull_markings', v.hull_markings],
+    ['hull_repair_history', v.hull_repair_history],
+    ['symmetry', v.symmetry],
+    ['material_dominant', v.material_dominant],
+    ['scale_cue_object', v.scale_cue_object],
+    ['interior_architecture', v.interior_architecture],
+    ['cockpit_style', v.cockpit_style],
+    ['engine_signature', v.engine_signature],
+  ]));
+
+  out.push(renderKeyValueSection('Narrative', [
+    ['role', n.role],
+    ['current_status', n.current_status],
+    ['trade_capacity', n.trade_capacity],
+    ['named_crew', n.named_crew],
+    ['named_passengers', n.named_passengers],
+  ]));
+
+  out.push(renderSection('History beats', n.history_beats || null));
+
+  if (Array.isArray(n.relationships) && n.relationships.length) {
+    const relBullets = n.relationships.map((r) => {
+      const note = r.note ? ` — ${r.note}` : '';
+      return `${r.edge_type} ${r.target_id}${note}`;
+    });
+    out.push(renderSection('Relationships', relBullets));
+  }
+
+  if (m && typeof m === 'object' && Object.values(m).some((vv) => vv != null)) {
+    out.push(renderKeyValueSection('Mechanical', [
+      ['hull_integrity_starting', m.hull_integrity_starting],
+      ['fuel_capacity_starting', m.fuel_capacity_starting],
+      ['cargo_slots', m.cargo_slots],
+      ['modification_slots', m.modification_slots],
+      ['crew_capacity', m.crew_capacity],
+      ['combat_capability', m.combat_capability],
+    ]));
+  }
+
+  out.push(renderSection('Forbidden', fm.forbidden_inputs || null));
+  out.push(renderSection('Sources', fm.sources || null));
+  out.push(renderSection('Canon refs', fm.canon_refs || null));
+
+  if (entry.body && entry.body.trim()) {
+    out.push(`## Notes\n${entry.body.trim()}\n`);
+  }
+
+  return out.join('');
+}
+
+function titleFromId(id) {
+  if (!id) return 'Untitled';
+  return id.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
+export { buildCaption as _buildCaption, buildPromptTemplate as _buildPromptTemplate, buildContext as _buildContext };

package/lib/canon-build/emitters/species.js

@@ -0,0 +1,165 @@
+/**
+ * Species emitter (Star Freight D6).
+ *
+ * Species-level forbidden_morphology_drift is the schema-level home for the
+ * "alien needs `human` in negative" rule (feedback_alien_negative_prompt.md).
+ * Every member character inherits it — species is the entry, not a per-character
+ * redundancy.
+ *
+ * Caption: trigger + " style, a " + biology_class + " species, " +
+ *          body_plan + ", " + signature_appendages
+ * Prompt positive: body_plan + anatomy_descriptors +
+ *                  involuntary_expression_channel + palette + signature_features
+ * Prompt negative: forbidden_inputs + forbidden_morphology_drift (the species-
+ *                  level alien guard)
+ */
+
+import { contextFrontmatter, renderKeyValueSection, renderSection } from './base.js';
+
+const SCHEMA_KIND = 'species';
+
+export function emitSpecies(entry, ctx) {
+  const fm = entry.frontmatter;
+  return {
+    schemaKind: SCHEMA_KIND,
+    caption: buildCaption(fm, ctx),
+    prompt: buildPromptTemplate(fm),
+    context: buildContext(entry, ctx),
+  };
+}
+
+function buildCaption(fm, ctx) {
+  const v = fm.visual || {};
+  const segments = [];
+  if (ctx.trigger) segments.push(`${ctx.trigger} style`);
+
+  const bio = fm.biology_class || 'species';
+  segments.push(`a ${bio} species`);
+
+  if (v.body_plan) segments.push(v.body_plan);
+  const anatomy = v.anatomy_descriptors || {};
+  if (anatomy.signature_appendages) segments.push(anatomy.signature_appendages);
+
+  return segments.join(', ');
+}
+
+function buildPromptTemplate(fm) {
+  const v = fm.visual || {};
+  const anatomy = v.anatomy_descriptors || {};
+  const lines = [];
+  lines.push(`{# auto-generated canon-build prompt template — do not hand-edit #}`);
+  lines.push(`{{ trigger }} style, a ${fm.biology_class || 'species'}, ${v.body_plan || ''}.`);
+
+  if (typeof anatomy.arm_count === 'number') {
+    lines.push(`{# arms #} ${anatomy.arm_count} arms`);
+  }
+  if (anatomy.locomotion) lines.push(`{# locomotion #} ${anatomy.locomotion}`);
+  if (anatomy.sensory_organs) lines.push(`{# senses #} ${anatomy.sensory_organs}`);
+  if (anatomy.skin_or_integument) lines.push(`{# integument #} ${anatomy.skin_or_integument}`);
+  if (anatomy.signature_appendages) lines.push(`{# appendages #} ${anatomy.signature_appendages}`);
+  if (v.involuntary_expression_channel) {
+    lines.push(`{# expression #} ${v.involuntary_expression_channel}`);
+  }
+  if (Array.isArray(v.palette) && v.palette.length) {
+    lines.push(`{# palette #} ${v.palette.join(' ')}`);
+  }
+  if (Array.isArray(fm.signature_features) && fm.signature_features.length) {
+    lines.push(`{# signature #} ${fm.signature_features.join(', ')}`);
+  }
+
+  lines.push('---');
+  lines.push(`{{ negative_base }}`);
+  if (Array.isArray(v.forbidden_morphology_drift) && v.forbidden_morphology_drift.length) {
+    lines.push(`, ${v.forbidden_morphology_drift.join(', ')}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function buildContext(entry, ctx) {
+  const fm = entry.frontmatter;
+  const n = fm.narrative || {};
+  const v = fm.visual || {};
+  const comm = fm.communication_modality || {};
+  const culture = fm.cultural_stance || {};
+  const rel = fm.relation_to_humans || {};
+  const out = [];
+
+  out.push(contextFrontmatter({
+    entityId: fm.id,
+    schemaKind: SCHEMA_KIND,
+    generatedFrom: ctx.generatedFrom,
+    entryHash: ctx.entryHash,
+  }));
+  out.push(`# ${titleFromId(fm.id)}\n`);
+
+  out.push(renderKeyValueSection('Identity', [
+    ['biology_class', fm.biology_class],
+    ['scaffold', fm.scaffold],
+  ]));
+
+  out.push(renderKeyValueSection('Communication', [
+    ['primary_language', comm.primary_language],
+    ['nonverbal_channel', comm.nonverbal_channel],
+    ['can_lie', comm.can_lie],
+    ['signal_incompatibility_with_humans', comm.signal_incompatibility_with_humans],
+  ]));
+
+  out.push(renderKeyValueSection('Cultural stance', [
+    ['time_horizon', culture.time_horizon],
+    ['core_value', culture.core_value],
+    ['death_rite', culture.death_rite],
+    ['trade_idiom', culture.trade_idiom],
+    ['greeting_protocol', culture.greeting_protocol],
+  ]));
+
+  const anatomy = v.anatomy_descriptors || {};
+  out.push(renderKeyValueSection('Visual', [
+    ['body_plan', v.body_plan],
+    ['locomotion', anatomy.locomotion],
+    ['arm_count', anatomy.arm_count],
+    ['sensory_organs', anatomy.sensory_organs],
+    ['skin_or_integument', anatomy.skin_or_integument],
+    ['signature_appendages', anatomy.signature_appendages],
+    ['palette', v.palette],
+    ['involuntary_expression_channel', v.involuntary_expression_channel],
+    ['sexual_dimorphism', v.sexual_dimorphism],
+  ]));
+
+  out.push(renderSection('Forbidden morphology drift', v.forbidden_morphology_drift || null));
+
+  out.push(renderKeyValueSection('Relation to humans', [
+    ['baseline_stance', rel.baseline_stance],
+    ['narrative_framing', rel.narrative_framing],
+    ['gameplay_integration', rel.gameplay_integration],
+  ]));
+
+  out.push(renderKeyValueSection('Narrative', [
+    ['role', n.role],
+  ]));
+  out.push(renderSection('Canonical practices', n.canonical_practices || null));
+
+  if (Array.isArray(n.relationships) && n.relationships.length) {
+    const relBullets = n.relationships.map((r) => {
+      const note = r.note ? ` — ${r.note}` : '';
+      return `${r.edge_type} ${r.target_id}${note}`;
+    });
+    out.push(renderSection('Relationships', relBullets));
+  }
+
+  out.push(renderSection('Forbidden', fm.forbidden_inputs || null));
+  out.push(renderSection('Sources', fm.sources || null));
+  out.push(renderSection('Canon refs', fm.canon_refs || null));
+
+  if (entry.body && entry.body.trim()) {
+    out.push(`## Notes\n${entry.body.trim()}\n`);
+  }
+
+  return out.join('');
+}
+
+function titleFromId(id) {
+  if (!id) return 'Untitled';
+  return id.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
+export { buildCaption as _buildCaption, buildPromptTemplate as _buildPromptTemplate, buildContext as _buildContext };

package/lib/canon-build/frontmatter.js

@@ -0,0 +1,76 @@
+/**
+ * Frontmatter parser for canon entry Markdown files.
+ *
+ * Canon entry shape:
+ *   ---
+ *   <YAML frontmatter>
+ *   ---
+ *   <Markdown body prose>
+ *
+ * The YAML block is the schema-validated object (fed to emitters' caption
+ * + prompt tracks). The body is free prose (fed to emitters' context track
+ * only, per the captions-are-load-bearing invariant — prose must never
+ * splice into captions).
+ */
+
+import { parse as parseYaml } from 'yaml';
+
+const FENCE = '---';
+
+/**
+ * Split a file into { frontmatter, body }.
+ *
+ * Returns { frontmatter: Object, body: string } on success.
+ * Throws with a structured message on malformed input.
+ *
+ * Leading/trailing whitespace before/after the fences is tolerated; a file
+ * without a closing fence throws rather than guessing where the body starts.
+ *
+ * @param {string} text — full file contents
+ * @param {string} filename — for error messages only
+ */
+export function parseFrontmatter(text, filename = '<input>') {
+  const normalized = text.replace(/\r\n/g, '\n');
+
+  // Must start with --- (optionally preceded by BOM / whitespace)
+  const stripped = normalized.replace(/^\uFEFF/, '').trimStart();
+  if (!stripped.startsWith(FENCE)) {
+    throw new Error(`parseFrontmatter: ${filename} does not begin with a "---" frontmatter fence`);
+  }
+
+  // Find the closing fence. It must be on its own line.
+  const afterOpen = stripped.slice(FENCE.length);
+  // Skip the newline after the opening fence.
+  const newlineIdx = afterOpen.indexOf('\n');
+  if (newlineIdx < 0) {
+    throw new Error(`parseFrontmatter: ${filename} has no newline after the opening fence`);
+  }
+
+  const rest = afterOpen.slice(newlineIdx + 1);
+  // Look for "\n---\n" or "\n---" at the end of rest.
+  const closeMatch = rest.match(/\n---(\r?\n|$)/);
+  if (!closeMatch) {
+    throw new Error(`parseFrontmatter: ${filename} has no closing "---" fence`);
+  }
+  const closeIdx = closeMatch.index;
+
+  const yamlSource = rest.slice(0, closeIdx);
+  const body = rest.slice(closeIdx + closeMatch[0].length);
+
+  let frontmatter;
+  try {
+    frontmatter = parseYaml(yamlSource);
+  } catch (err) {
+    throw new Error(`parseFrontmatter: ${filename} frontmatter is not valid YAML (${err.message})`);
+  }
+
+  if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    throw new Error(`parseFrontmatter: ${filename} frontmatter must be a YAML object (got ${typeof frontmatter})`);
+  }
+
+  return {
+    frontmatter,
+    body: body.replace(/^\n+/, ''),       // trim leading newlines before body
+    rawYaml: yamlSource,
+  };
+}