@owlmeans/viable-common 0.0.44 → 0.0.46

package/src/scaffold/helpers.ts

@@ -1,81 +1,18 @@
-import type { ScaffoldPlan, ScaffoldStoryPlan, ShareKind } from './types.js'
+import { scaffoldShareHelper } from './share.js'
+import type { ScaffoldPlan, ShareKind } from './types.js'
 
-/**
- * ONE reading of who owns a drawn artifact, so no consumer has to interpret the plan itself.
- *
- * The plan carries `sharesWidgetWith` / `sharesScreenWith` as untrusted hints — a model may drop
- * them, invent a code, point forwards, or build a cycle. These resolve all of that away, and
- * every one is TOTAL: a code the plan does not hold answers itself, which is the unshared
- * behaviour and therefore exactly today's drawn tree.
- *
- * Pure and IO-free. `fillScaffoldPlan` normalises a plan through them before anything is stamped,
- * so the stampers and the scaffold loop can read a plan that is already sane.
- */
+/** @deprecated compat:factory-refactor — use `scaffoldShareHelper.shareOwner(…)` */
+export const shareOwner = (plan: Pick<ScaffoldPlan, 'stories'>, code: string, kind: ShareKind = 'widget'): string =>
+  scaffoldShareHelper.shareOwner(plan, code, kind)
 
-const pointerOf = (story: ScaffoldStoryPlan, kind: ShareKind): string | undefined =>
-  kind === 'widget' ? story.sharesWidgetWith : story.sharesScreenWith
+/** @deprecated compat:factory-refactor — use `scaffoldShareHelper.shareGroups(…)` */
+export const shareGroups = (plan: Pick<ScaffoldPlan, 'stories'>, kind: ShareKind = 'widget'): Map<string, string[]> =>
+  scaffoldShareHelper.shareGroups(plan, kind)
 
-/**
- * The code whose artifact this story renders — itself when it owns one.
- *
- * Backward-only and bounded: an arrow is followed only to a story EARLIER in plan order, which
- * makes a cycle unrepresentable rather than merely unlikely, and makes the owner the earliest
- * member of its group. That is what keeps `widgetDefinition(owner)` stable — the name is a
- * function of one code, never of the group, so adding a member renames nothing.
- */
-export const shareOwner = (
-  plan: Pick<ScaffoldPlan, 'stories'>, code: string, kind: ShareKind = 'widget'
-): string => {
-  const order = new Map(plan.stories.map((story, index) => [story.code, index]))
-  const byCode = new Map(plan.stories.map(story => [story.code, story]))
+/** @deprecated compat:factory-refactor — use `scaffoldShareHelper.shareMembers(…)` */
+export const shareMembers = (plan: Pick<ScaffoldPlan, 'stories'>, owner: string, kind: ShareKind = 'widget'): string[] =>
+  scaffoldShareHelper.shareMembers(plan, owner, kind)
 
-  let current = code
-  // Bounded by the list length: every hop strictly decreases the plan index, so it terminates.
-  for (let hop = 0; hop <= plan.stories.length; hop++) {
-    const story = byCode.get(current)
-    const target = story != null ? pointerOf(story, kind) : undefined
-    if (story == null || target == null || target === '' || target === current) {
-      return current
-    }
-    const here = order.get(current)
-    const there = order.get(target)
-    // Unknown, forward or self-referential — none of them is a group, so the story owns its own.
-    if (here == null || there == null || there >= here) {
-      return current
-    }
-    current = target
-  }
-
-  return current
-}
-
-/**
- * Owner code → every member, owner first, in plan order.
- *
- * The shape the stampers need: one artifact per entry, and the full member list for the notice
- * that names them.
- */
-export const shareGroups = (
-  plan: Pick<ScaffoldPlan, 'stories'>, kind: ShareKind = 'widget'
-): Map<string, string[]> => {
-  const groups = new Map<string, string[]>()
-  for (const story of plan.stories) {
-    const owner = shareOwner(plan, story.code, kind)
-    const members = groups.get(owner) ?? []
-    if (!members.includes(owner)) members.push(owner)
-    if (!members.includes(story.code)) members.push(story.code)
-    groups.set(owner, members)
-  }
-
-  return groups
-}
-
-/** Every story that renders this owner's artifact, owner first. Total: an owner alone answers `[code]`. */
-export const shareMembers = (
-  plan: Pick<ScaffoldPlan, 'stories'>, owner: string, kind: ShareKind = 'widget'
-): string[] => shareGroups(plan, kind).get(owner) ?? [owner]
-
-/** Whether this story draws the artifact, as opposed to rendering somebody else's. */
-export const ownsShare = (
-  plan: Pick<ScaffoldPlan, 'stories'>, code: string, kind: ShareKind = 'widget'
-): boolean => shareOwner(plan, code, kind) === code
+/** @deprecated compat:factory-refactor — use `scaffoldShareHelper.ownsShare(…)` */
+export const ownsShare = (plan: Pick<ScaffoldPlan, 'stories'>, code: string, kind: ShareKind = 'widget'): boolean =>
+  scaffoldShareHelper.ownsShare(plan, code, kind)

package/src/scaffold/index.ts

@@ -1,4 +1,8 @@
 export * from './consts.js'
 export * from './schemas.js'
 export type * from './types.js'
+export type * from './share/types.js'
+export type * from './landing/types.js'
+export * from './share.js'
+export * from './landing.js'
 export * from './helpers.js'

package/src/scaffold/landing/types.ts

@@ -0,0 +1,48 @@
+import type { GuestHomePlan, LandingBand, LandingMenuEntry, LandingSlot } from '../types.js'
+
+/**
+ * ONE reading of what a landing page draws, so the stamper, the menu and the link planner agree.
+ *
+ * Pure, IO-free and total over a stored plan of any age: every optional band may be absent or
+ * `null`, and blank model text counts as absent.
+ */
+export interface LandingPlanHelper {
+  /**
+   * The bands a landing page draws, in the house order `LANDING_BAND_ORDER`.
+   *
+   * One presence rule per band:
+   *
+   * - `hero`, `features`, `problem` (problem and solution) — always;
+   * - `steps` — at least one step with a title;
+   * - `use-cases` — at least `LANDING_USE_CASES.min` titled cases;
+   * - `differentiator` — at least `LANDING_CONTRAST.min` contrast rows filled on both sides,
+   *   OR a title and a text: the band is a heading and a paragraph, and the table under them is
+   *   drawn only when it has enough rows;
+   * - `approach` — at least `LANDING_PRINCIPLES.min` titled principles;
+   * - `testimonials` — at least two quotes;
+   * - `about` — a title and a text;
+   * - `closing` — whenever the plan carries one.
+   */
+  landingBandsOf: (home: GuestHomePlan) => LandingBand[]
+  /**
+   * The guest header menu a page draws.
+   *
+   * Keeps only entries whose band the page draws (and whose anchor exists), the first of each
+   * anchor, in page order; caps the list at `max` (never below `LANDING_MENU.min`); then pads
+   * to `LANDING_MENU.min` with `how`, `features` and the first other band the page draws. A
+   * label falls back to the page's own section label, then to `LANDING_ANCHOR_LABELS`.
+   */
+  landingMenuOf: (home: GuestHomePlan, max?: number) => LandingMenuEntry[]
+  /**
+   * The buttons and links of a landing page that exist — the places a home link can attach to,
+   * in page order.
+   *
+   * - `hero.cta` and `closing.primary` (with a closing) — only without a usable gate, which takes
+   *   their place (`LANDING_GATE_SLOTS`);
+   * - `hero.secondary` — only without a usable gate, and only when the plan labels it;
+   * - `hero.browse`, `closing.secondary` — when the plan labels them;
+   * - `closing.link.N` — one per titled closing card, at most two;
+   * - `useCase.N` — one per drawn case, when the use-cases band is drawn.
+   */
+  homeSlotsOf: (home: GuestHomePlan) => LandingSlot[]
+}

package/src/scaffold/landing.ts

@@ -0,0 +1,120 @@
+import {
+  LANDING_ANCHOR_BAND, LANDING_ANCHOR_LABELS, LANDING_ANCHORS, LANDING_BAND_ORDER, LANDING_CONTRAST,
+  LANDING_MENU, LANDING_PRINCIPLES, LANDING_USE_CASES,
+} from './consts.js'
+import type { GuestHomePlan, LandingAnchor, LandingBand, LandingMenuEntry, LandingSlot } from './types.js'
+import type { LandingPlanHelper } from './landing/types.js'
+
+const filled = (value: string | null | undefined): boolean => (value?.trim() ?? '') !== ''
+
+export const createLandingPlanHelper = (): LandingPlanHelper => {
+  /** The use cases a page draws: titled ones, at most {@link LANDING_USE_CASES}.max. */
+  const drawnUseCases = (home: GuestHomePlan) =>
+    (home.useCases?.cases ?? []).filter(entry => filled(entry.title)).slice(0, LANDING_USE_CASES.max)
+
+  /** The closing link cards a page draws: titled ones, at most two. */
+  const drawnClosingLinks = (home: GuestHomePlan) =>
+    (home.closing?.links ?? []).filter(entry => filled(entry.title)).slice(0, 2)
+
+  /** Whether the gate is drawn: a gate is a form, and one without fields is no gate at all. */
+  const usableGate = (home: GuestHomePlan): boolean =>
+    home.gate != null && (home.gate.fields ?? []).length > 0
+
+  /** One presence rule per band — see {@link LandingPlanHelper.landingBandsOf}. */
+  const bandPresent: Record<LandingBand, (home: GuestHomePlan) => boolean> = {
+    hero: () => true,
+    steps: home => (home.steps ?? []).some(step => filled(step.title)),
+    features: () => true,
+    'use-cases': home => drawnUseCases(home).length >= LANDING_USE_CASES.min,
+    problem: () => true,
+    differentiator: home => {
+      const band = home.differentiator
+      if (band == null) return false
+      const rows = (band.contrast ?? []).filter(row => filled(row.usual) && filled(row.ours))
+
+      return rows.length >= LANDING_CONTRAST.min || (filled(band.title) && filled(band.text))
+    },
+    approach: home =>
+      (home.approach?.principles ?? []).filter(entry => filled(entry.title)).length >= LANDING_PRINCIPLES.min,
+    testimonials: home => (home.testimonials ?? []).filter(entry => filled(entry.quote)).length >= 2,
+    about: home => home.about != null && filled(home.about.title) && filled(home.about.text),
+    closing: home => home.closing != null,
+  }
+
+  const landingBandsOf: LandingPlanHelper['landingBandsOf'] = home =>
+    LANDING_BAND_ORDER.filter(band => bandPresent[band](home))
+
+  /** The page's own section label for an anchor's band, when the plan wrote one. */
+  const sectionLabel = (home: GuestHomePlan, anchor: LandingAnchor): string | null | undefined => {
+    const labels = home.labels ?? {}
+    switch (anchor) {
+      case 'how': return labels.steps
+      case 'features': return labels.features
+      case 'use-cases': return labels.useCases
+      case 'why': return labels.differentiator
+      case 'approach': return labels.approach
+      case 'community': return labels.testimonials
+      case 'about': return labels.about
+    }
+  }
+
+  const landingMenuOf: LandingPlanHelper['landingMenuOf'] = (home, max = LANDING_MENU.max) => {
+    const bands = landingBandsOf(home)
+    const drawn = (anchor: LandingAnchor) =>
+      LANDING_ANCHORS.includes(anchor) && bands.includes(LANDING_ANCHOR_BAND[anchor])
+    const order = (anchor: LandingAnchor) => LANDING_ANCHORS.indexOf(anchor)
+    const label = (anchor: LandingAnchor, own?: string | null): string => {
+      const candidates = [own, sectionLabel(home, anchor)]
+      const chosen = candidates.find(filled)
+
+      return chosen?.trim() ?? LANDING_ANCHOR_LABELS[anchor]
+    }
+
+    const chosen: LandingMenuEntry[] = []
+    for (const entry of home.menu ?? []) {
+      if (entry == null || !drawn(entry.anchor) || chosen.some(kept => kept.anchor === entry.anchor)) {
+        continue
+      }
+      chosen.push({ anchor: entry.anchor, label: label(entry.anchor, entry.label) })
+    }
+    chosen.sort((a, b) => order(a.anchor) - order(b.anchor))
+    chosen.splice(Math.max(LANDING_MENU.min, max))
+
+    const padding: LandingAnchor[] = ['how', 'features', ...LANDING_ANCHORS.filter(
+      anchor => anchor !== 'how' && anchor !== 'features'
+    )]
+    for (const anchor of padding) {
+      if (chosen.length >= LANDING_MENU.min) break
+      if (drawn(anchor) && !chosen.some(kept => kept.anchor === anchor)) {
+        chosen.push({ anchor, label: label(anchor) })
+      }
+    }
+
+    return chosen.sort((a, b) => order(a.anchor) - order(b.anchor))
+  }
+
+  const homeSlotsOf: LandingPlanHelper['homeSlotsOf'] = home => {
+    const gate = usableGate(home)
+    const slots: LandingSlot[] = []
+
+    if (!gate) slots.push('hero.cta')
+    if (!gate && filled(home.hero.secondary?.label)) slots.push('hero.secondary')
+    if (filled(home.hero.browse?.label)) slots.push('hero.browse')
+
+    if (bandPresent['use-cases'](home)) {
+      drawnUseCases(home).forEach((_, index) => slots.push(`useCase.${index + 1}` as LandingSlot))
+    }
+
+    if (home.closing != null) {
+      if (!gate) slots.push('closing.primary')
+      if (filled(home.closing.secondary?.label)) slots.push('closing.secondary')
+      drawnClosingLinks(home).forEach((_, index) => slots.push(`closing.link.${index + 1}` as LandingSlot))
+    }
+
+    return slots
+  }
+
+  return { landingBandsOf, landingMenuOf, homeSlotsOf }
+}
+
+export const landingPlanHelper = createLandingPlanHelper()

package/src/scaffold/schemas.ts

@@ -1,7 +1,9 @@
 import type { JSONSchemaType } from 'ajv'
 
 import { ProjectArea } from '../areas/consts.js'
-import { BENTO_FRAGMENT_KINDS, LANDING_GATE_FIELD_KINDS, WidgetKind } from './consts.js'
+import {
+  BENTO_FRAGMENT_KINDS, LANDING_ANCHORS, LANDING_GATE_FIELD_KINDS, LANDING_SLOTS, WidgetKind,
+} from './consts.js'
 import type {
   BentoFragment, GuestHomePlan, LandingGateAnswer, LandingGateField, LandingGatePlan, ProductIdentity,
   ScaffoldAreaPlan, ScaffoldPlan, ScaffoldStoryPlan, SketchContent,
@@ -352,6 +354,27 @@ const LandingGatePlanSchema: JSONSchemaType<LandingGatePlan> = {
   additionalProperties: false,
 }
 
+/**
+ * The `basis` every band added with the gated landing page carries — one text, so the model reads
+ * the same rule on each band and the check downstream has one contract to enforce.
+ */
+const BASIS_TEXT = 'A short passage (a few words up to one sentence) copied EXACTLY, word for word,'
+  + ' from the person\'s own words, the specification or the vision, that this band is built on.'
+  + ' It is checked; a band whose basis is not found there is removed.'
+
+const basis = { type: 'string' as const, description: BASIS_TEXT }
+
+/** A title + text pair inside a band — required, because the band object itself is optional. */
+const titledText = (title: string, text: string) => ({
+  type: 'object' as const,
+  properties: {
+    title: { type: 'string' as const, description: title },
+    text: { type: 'string' as const, description: text },
+  },
+  required: ['title', 'text'] as ('title' | 'text')[],
+  additionalProperties: false as const,
+})
+
 const GuestHomePlanSchema: JSONSchemaType<GuestHomePlan> = {
   type: 'object',
   title: 'GuestHomePlan',
@@ -425,7 +448,7 @@ const GuestHomePlanSchema: JSONSchemaType<GuestHomePlan> = {
         + ' specification actually describes. Give most of them a fragment'
     },
     testimonials: {
-      type: 'array',
+      type: 'array', nullable: true,
       items: {
         type: 'object',
         properties: {
@@ -436,7 +459,8 @@ const GuestHomePlanSchema: JSONSchemaType<GuestHomePlan> = {
         required: ['quote', 'name', 'role'],
         additionalProperties: false,
       },
-      description: '2 illustrative testimonials. No ratings, no numbers, no company names'
+      description: 'OPTIONAL: 0 or exactly 2 illustrative testimonials; leave it out unless the'
+        + ' product\'s end users choose it for themselves. No ratings, no numbers, no company names'
     },
     steps: {
       type: 'array', nullable: true,
@@ -452,6 +476,94 @@ const GuestHomePlanSchema: JSONSchemaType<GuestHomePlan> = {
       description: '"How it works": 3 steps taken from the main flow, in order, the last one'
         + ' delivering the value'
     },
+    useCases: {
+      type: 'object', nullable: true,
+      description: 'OPTIONAL "Use cases": who the product is for, case by case - only cases the'
+        + ' person\'s words, the specification or the vision actually name',
+      properties: {
+        cases: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              audience: { type: 'string', description: 'Who this case is for, 1-4 words' },
+              title: { type: 'string', description: 'What they do with the product, 2-5 words' },
+              text: { type: 'string', description: 'One sentence on what it gives them' },
+            },
+            required: ['audience', 'title', 'text'],
+            additionalProperties: false,
+          },
+          description: '2 to 4 cases',
+        },
+        basis,
+      },
+      required: ['cases', 'basis'],
+      additionalProperties: false,
+    },
+    differentiator: {
+      type: 'object', nullable: true,
+      description: 'OPTIONAL "Why us": what this product does differently from the usual way,'
+        + ' only when the person\'s words, the specification or the vision say so',
+      properties: {
+        title: { type: 'string', description: 'The difference in 3-6 words' },
+        text: { type: 'string', description: 'One or two sentences on it. No invented numbers' },
+        contrast: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              usual: { type: 'string', description: 'How it is usually done, at most 6 words' },
+              ours: { type: 'string', description: 'How this product does it, at most 6 words' },
+            },
+            required: ['usual', 'ours'],
+            additionalProperties: false,
+          },
+          description: '2 to 3 usual-vs-ours rows',
+        },
+        usualLabel: {
+          type: 'string', nullable: true,
+          description: 'OPTIONAL heading over the usual column, 1-2 words - e.g. "Usually"',
+        },
+        oursLabel: {
+          type: 'string', nullable: true,
+          description: 'OPTIONAL heading over this product\'s column, 1-2 words - e.g. "With us"',
+        },
+        basis,
+      },
+      required: ['title', 'text', 'contrast', 'basis'],
+      additionalProperties: false,
+    },
+    approach: {
+      type: 'object', nullable: true,
+      description: 'OPTIONAL "How we work": the principles the product is run by, only when the'
+        + ' person\'s words, the specification or the vision state them',
+      properties: {
+        title: {
+          type: 'string', nullable: true,
+          description: 'OPTIONAL heading of the band, one short concrete sentence',
+        },
+        principles: {
+          type: 'array',
+          items: titledText('The principle, 2-4 words', 'One sentence on what it means in practice'),
+          description: '3 to 4 principles',
+        },
+        basis,
+      },
+      required: ['principles', 'basis'],
+      additionalProperties: false,
+    },
+    about: {
+      type: 'object', nullable: true,
+      description: 'OPTIONAL "About": who is behind the product, only when the person\'s words,'
+        + ' the specification or the vision say who',
+      properties: {
+        title: { type: 'string', description: 'The heading, 2-5 words' },
+        text: { type: 'string', description: 'Two or three sentences. Nothing invented' },
+        basis,
+      },
+      required: ['title', 'text', 'basis'],
+      additionalProperties: false,
+    },
     labels: {
       type: 'object', nullable: true,
       description: 'The small label over each section and that section\'s heading, in the product\'s'
@@ -472,6 +584,17 @@ const GuestHomePlanSchema: JSONSchemaType<GuestHomePlan> = {
         },
         problem: { type: 'string', nullable: true, description: 'e.g. "The problem"' },
         solution: { type: 'string', nullable: true, description: 'e.g. "The solution"' },
+        useCases: { type: 'string', nullable: true, description: 'e.g. "Use cases"' },
+        useCasesTitle: {
+          type: 'string', nullable: true, description: 'e.g. "Made for every kind of home baker."'
+        },
+        differentiator: { type: 'string', nullable: true, description: 'e.g. "Why us"' },
+        approach: { type: 'string', nullable: true, description: 'e.g. "How we work"' },
+        approachTitle: {
+          type: 'string', nullable: true,
+          description: 'e.g. "Small batches, honest notes." - used when the approach has no title'
+        },
+        about: { type: 'string', nullable: true, description: 'e.g. "About"' },
       },
       required: [],
       additionalProperties: false,
@@ -511,8 +634,57 @@ const GuestHomePlanSchema: JSONSchemaType<GuestHomePlan> = {
       description: 'ONLY when you were given a landing story; omit it otherwise. '
         + LandingGatePlanSchema.description,
     },
+    menu: {
+      type: 'array', nullable: true,
+      items: {
+        type: 'object',
+        properties: {
+          anchor: {
+            type: 'string',
+            enum: LANDING_ANCHORS,
+            description: 'The band it jumps to: how (how it works), features, use-cases, why'
+              + ' (the differentiator), approach (how we work), community (testimonials), about'
+          },
+          label: { type: 'string', description: 'The menu word, 1-2 words in the product\'s language' },
+        },
+        required: ['anchor', 'label'],
+        additionalProperties: false,
+      },
+      description: 'The header menu of the landing page: 2 to 4 entries, each pointing at a band'
+        + ' this page carries, in page order'
+    },
+    links: {
+      type: 'array', nullable: true,
+      items: {
+        type: 'object',
+        properties: {
+          slot: {
+            type: 'string',
+            enum: LANDING_SLOTS,
+            description: 'The button: hero.cta, hero.secondary, hero.browse, closing.primary,'
+              + ' closing.secondary, closing.link.1/2 (the closing cards), useCase.1-4 (the use'
+              + ' cases in order). Without a gate only; with one, hero.cta, hero.secondary and'
+              + ' closing.primary do not exist'
+          },
+          story: {
+            type: 'string',
+            description: 'The story code, copied EXACTLY from the story list given to you'
+          },
+        },
+        required: ['slot', 'story'],
+        additionalProperties: false,
+      },
+      description: 'Which home buttons open which user story. Leave it out when undecided; an'
+        + ' empty list means decided: none. At most one entry per button'
+    },
+    linksDecided: {
+      type: 'array', nullable: true,
+      items: { type: 'string' },
+      description: 'Story codes whose links were decided at development time (a decision of no'
+        + ' button included). Absent on a plan whose links the planner decided. Filled by code'
+    },
   },
-  required: ['hero', 'problem', 'solution', 'features', 'testimonials'],
+  required: ['hero', 'problem', 'solution', 'features'],
   additionalProperties: false,
 }
 
@@ -567,10 +739,14 @@ export const ScaffoldPlanSchema: JSONSchemaType<ScaffoldPlan> = {
   additionalProperties: false,
 }
 
+/** The guest home's keys a model may answer: `linksDecided` is written by code, never asked. */
+const { linksDecided: _linksDecided, ...answeredHomeProperties } = GuestHomePlanSchema.properties!
+
 /**
  * The plan as the planning MODEL answers it — {@link ScaffoldPlanSchema} with the gate held to the
- * form. The stored schema keeps the pre-form gate keys optional so an old plan still validates;
- * offering them to the model would let it write a chip picker again. Typed as the stored plan
+ * form and without the code-written `linksDecided`. The stored schema keeps the pre-form gate keys
+ * optional so an old plan still validates; offering them to the model would let it write a chip
+ * picker again. Typed as the stored plan
  * because every answer is one: the answer's gate is a subset of the stored gate.
  */
 export const ScaffoldPlanAnswerSchema = {
@@ -580,7 +756,7 @@ export const ScaffoldPlanAnswerSchema = {
     guestHome: {
       ...GuestHomePlanSchema,
       properties: {
-        ...GuestHomePlanSchema.properties,
+        ...answeredHomeProperties,
         gate: {
           ...LandingGateAnswerSchema,
           nullable: true,

package/src/scaffold/share/types.ts

@@ -0,0 +1,35 @@
+import type { ScaffoldPlan, ShareKind } from '../types.js'
+
+/**
+ * ONE reading of who owns a drawn artifact, so no consumer has to interpret the plan itself.
+ *
+ * The plan carries `sharesWidgetWith` / `sharesScreenWith` as untrusted hints — a model may drop
+ * them, invent a code, point forwards, or build a cycle. These resolve all of that away, and
+ * every one is TOTAL: a code the plan does not hold answers itself, which is the unshared
+ * behaviour and therefore exactly today's drawn tree.
+ *
+ * Pure and IO-free. `fillScaffoldPlan` normalises a plan through them before anything is stamped,
+ * so the stampers and the scaffold loop can read a plan that is already sane.
+ */
+export interface ScaffoldShareHelper {
+  /**
+   * The code whose artifact this story renders — itself when it owns one.
+   *
+   * Backward-only and bounded: an arrow is followed only to a story EARLIER in plan order, which
+   * makes a cycle unrepresentable rather than merely unlikely, and makes the owner the earliest
+   * member of its group. That is what keeps `widgetDefinition(owner)` stable — the name is a
+   * function of one code, never of the group, so adding a member renames nothing.
+   */
+  shareOwner: (plan: Pick<ScaffoldPlan, 'stories'>, code: string, kind?: ShareKind) => string
+  /**
+   * Owner code → every member, owner first, in plan order.
+   *
+   * The shape the stampers need: one artifact per entry, and the full member list for the notice
+   * that names them.
+   */
+  shareGroups: (plan: Pick<ScaffoldPlan, 'stories'>, kind?: ShareKind) => Map<string, string[]>
+  /** Every story that renders this owner's artifact, owner first. Total: an owner alone answers `[code]`. */
+  shareMembers: (plan: Pick<ScaffoldPlan, 'stories'>, owner: string, kind?: ShareKind) => string[]
+  /** Whether this story draws the artifact, as opposed to rendering somebody else's. */
+  ownsShare: (plan: Pick<ScaffoldPlan, 'stories'>, code: string, kind?: ShareKind) => boolean
+}

package/src/scaffold/share.ts

@@ -0,0 +1,60 @@
+import type { ScaffoldPlan, ScaffoldStoryPlan, ShareKind } from './types.js'
+import type { ScaffoldShareHelper } from './share/types.js'
+
+export const createScaffoldShareHelper = (): ScaffoldShareHelper => {
+  const pointerOf = (story: ScaffoldStoryPlan, kind: ShareKind): string | undefined =>
+    kind === 'widget' ? story.sharesWidgetWith : story.sharesScreenWith
+
+  const shareOwner = (
+    plan: Pick<ScaffoldPlan, 'stories'>, code: string, kind: ShareKind = 'widget'
+  ): string => {
+    const order = new Map(plan.stories.map((story, index) => [story.code, index]))
+    const byCode = new Map(plan.stories.map(story => [story.code, story]))
+
+    let current = code
+    // Bounded by the list length: every hop strictly decreases the plan index, so it terminates.
+    for (let hop = 0; hop <= plan.stories.length; hop++) {
+      const story = byCode.get(current)
+      const target = story != null ? pointerOf(story, kind) : undefined
+      if (story == null || target == null || target === '' || target === current) {
+        return current
+      }
+      const here = order.get(current)
+      const there = order.get(target)
+      // Unknown, forward or self-referential — none of them is a group, so the story owns its own.
+      if (here == null || there == null || there >= here) {
+        return current
+      }
+      current = target
+    }
+
+    return current
+  }
+
+  const shareGroups = (
+    plan: Pick<ScaffoldPlan, 'stories'>, kind: ShareKind = 'widget'
+  ): Map<string, string[]> => {
+    const groups = new Map<string, string[]>()
+    for (const story of plan.stories) {
+      const owner = shareOwner(plan, story.code, kind)
+      const members = groups.get(owner) ?? []
+      if (!members.includes(owner)) members.push(owner)
+      if (!members.includes(story.code)) members.push(story.code)
+      groups.set(owner, members)
+    }
+
+    return groups
+  }
+
+  const shareMembers = (
+    plan: Pick<ScaffoldPlan, 'stories'>, owner: string, kind: ShareKind = 'widget'
+  ): string[] => shareGroups(plan, kind).get(owner) ?? [owner]
+
+  const ownsShare = (
+    plan: Pick<ScaffoldPlan, 'stories'>, code: string, kind: ShareKind = 'widget'
+  ): boolean => shareOwner(plan, code, kind) === code
+
+  return { shareOwner, shareGroups, shareMembers, ownsShare }
+}
+
+export const scaffoldShareHelper = createScaffoldShareHelper()