@owlmeans/viable-common 0.0.43 → 0.0.45

package/src/planning/landing.ts

@@ -1,43 +1,33 @@
 import { TITLE_MAX } from '@owlmeans/planning'
+import { LANDING_STORY_SENTENCE } from './consts.js'
+import type { LandingSentenceHelper } from './landing/types.js'
 
-/**
- * The sentence a landing story's narrative carries — what a person reading the board sees.
- *
- * The AUTHORITY is the card's `fields.landing` flag, never this text: the design and development
- * stages key on the flag, and a person may reword the narrative at any time. The sentence exists so
- * the board says in plain words why this story is different, and so the analyst and the designer,
- * who read the narrative, write a screen that continues what the guest started.
- *
- * A constant, byte for byte, because {@link hasLandingSentence} is how a resumed decision step
- * knows it already appended it.
- */
-export const LANDING_STORY_SENTENCE = 'A visitor can start this on the landing page without an account;'
-  + ' after signing in they continue here with their choices carried over.'
-
-const normalized = (text: string): string => text.replace(/\s+/g, ' ')
-
-/** Whether a narrative already carries the landing sentence, whatever whitespace surrounds it. */
-export const hasLandingSentence = (title: string): boolean =>
-  normalized(title).includes(LANDING_STORY_SENTENCE)
-
-/**
- * The narrative with the landing sentence appended once.
- *
- * Idempotent — a narrative that already carries the sentence comes back unchanged, so a decision
- * step that is resumed after it wrote the card never appends a second copy. It never produces a
- * title longer than a card accepts (`TITLE_MAX`): a narrative with no room left is returned as it
- * is rather than cut, because a person's words are worth more than the note, and the flag on the
- * card still carries the fact.
- */
-export const withLandingSentence = (title: string): string => {
-  if (hasLandingSentence(title)) {
-    return title
-  }
-  const base = title.trimEnd()
-  if (base === '') {
-    return LANDING_STORY_SENTENCE
+export const createLandingSentenceHelper = (): LandingSentenceHelper => {
+  const normalized = (text: string): string => text.replace(/\s+/g, ' ')
+
+  const hasLandingSentence = (title: string): boolean =>
+    normalized(title).includes(LANDING_STORY_SENTENCE)
+
+  const withLandingSentence = (title: string): string => {
+    if (hasLandingSentence(title)) {
+      return title
+    }
+    const base = title.trimEnd()
+    if (base === '') {
+      return LANDING_STORY_SENTENCE
+    }
+    const joined = `${base} ${LANDING_STORY_SENTENCE}`
+
+    return joined.length > TITLE_MAX ? title : joined
   }
-  const joined = `${base} ${LANDING_STORY_SENTENCE}`
 
-  return joined.length > TITLE_MAX ? title : joined
+  return { hasLandingSentence, withLandingSentence }
 }
+
+export const landingSentenceHelper = createLandingSentenceHelper()
+
+/** @deprecated compat:factory-refactor — use `landingSentenceHelper.hasLandingSentence(…)` */
+export const hasLandingSentence = (title: string): boolean => landingSentenceHelper.hasLandingSentence(title)
+
+/** @deprecated compat:factory-refactor — use `landingSentenceHelper.withLandingSentence(…)` */
+export const withLandingSentence = (title: string): string => landingSentenceHelper.withLandingSentence(title)

package/src/planning/schemas.ts

@@ -1,13 +1,15 @@
 import type { JSONSchemaType } from 'ajv'
-import { CODE_MAX } from '@owlmeans/planning'
-import { ProjectArea } from '../areas/consts.js'
-import { TENANCY_QUOTE_MAX } from '../areas/tenancy.js'
+import { CODE_MAX, IntrinsicPolicy, IntrinsicStatus, SpecificationFormat, WorkcardKind, AnyTypeSchema, ProjectTypeSchema, RelationshipType, SpecificationSlot, StatusFlowSchema, WorkcardTypeSchema } from '@owlmeans/planning'
+import { ProjectArea, TENANCY_QUOTE_MAX } from '../areas/consts.js'
 import { CASE_QUOTE_MAX, WorkKind } from '../blueprint/consts.js'
 import { StoryKind } from '../ba/consts.js'
 import { ConnectLlm, ConnectTarget } from '../connect/consts.js'
 import { ProjectOriginSchema } from '../convert/schemas.js'
-import { StoryActor } from '../design/runtime.js'
+import { StoryActor, STORY_DESIGN_VERSION } from '../design/consts.js'
 import type { ViableProjectFields, ViableStoryFields } from './types.js'
+import { StoryDesignSchema } from '../design/schemas.js'
+import { ScaffoldPlanSchema } from '../scaffold/schemas.js'
+import { VIABLE_BUG_CODE, VIABLE_BUG_TYPE, VIABLE_DESIGN_REVISIONS_KEPT, VIABLE_IMPROVEMENT_CODE, VIABLE_IMPROVEMENT_TYPE, VIABLE_PROJECT_CODE, VIABLE_PROJECT_FLOW, VIABLE_PROJECT_TYPE, VIABLE_REQUIREMENT_CODE, VIABLE_REQUIREMENT_TYPE, VIABLE_SPEC_FLOW, VIABLE_SPEC_TYPE, VIABLE_STORY_CODE, VIABLE_STORY_FLOW, VIABLE_STORY_TYPE, ViableProjectStatus, ViableProjectTransition, ViableRelationship, ViableSpecCategory, ViableSpecStatus, ViableStoryStatus, ViableStoryTransition, ViableTone } from './consts.js'
 
 /**
  * The `fields` schema of a `viable:project` card.
@@ -109,3 +111,188 @@ export const ViableSpecFieldsSchema = {
   required: [],
   additionalProperties: false,
 } as unknown as JSONSchemaType<Record<string, never>>
+
+/**
+ * The story flow.
+ *
+ * `failed` maps to PLANNED: a failed story is work still to do, so "done" is the closed count and
+ * a retry is simply `start` again. `reset` from anywhere is the manual recovery — the one move a
+ * completed story still accepts.
+ */
+export const VIABLE_STORY_FLOW_SCHEMA: StatusFlowSchema = {
+  id: VIABLE_STORY_FLOW,
+  version: 1,
+  statuses: [
+    { key: ViableStoryStatus.Planned, intrinsic: IntrinsicStatus.Planned, initial: true, tone: ViableTone.Blue },
+    { key: ViableStoryStatus.InProgress, intrinsic: IntrinsicStatus.InProgress, tone: ViableTone.Yellow },
+    { key: ViableStoryStatus.Completed, intrinsic: IntrinsicStatus.Closed, tone: ViableTone.Green },
+    { key: ViableStoryStatus.Failed, intrinsic: IntrinsicStatus.Planned, tone: ViableTone.Red },
+  ],
+  transitions: [
+    {
+      name: ViableStoryTransition.Start,
+      from: [ViableStoryStatus.Planned, ViableStoryStatus.Failed],
+      to: ViableStoryStatus.InProgress,
+      explicit: true,
+    },
+    {
+      name: ViableStoryTransition.Complete,
+      from: [ViableStoryStatus.InProgress],
+      to: ViableStoryStatus.Completed,
+      explicit: true,
+    },
+    {
+      name: ViableStoryTransition.Fail,
+      from: [ViableStoryStatus.InProgress],
+      to: ViableStoryStatus.Failed,
+    },
+    { name: ViableStoryTransition.Reset, from: '*', to: ViableStoryStatus.Planned, explicit: true },
+  ],
+}
+
+/**
+ * The project flow.
+ *
+ * A create lands at `draft`; confirming the brief is `confirm`; the end of an initialization is
+ * `activate`. A reinitialization and a failed initialization are SLOT facts, not transitions, and
+ * destroying a project is a `delete` plus the platform's cascade — never `archive`.
+ */
+export const VIABLE_PROJECT_FLOW_SCHEMA: StatusFlowSchema = {
+  id: VIABLE_PROJECT_FLOW,
+  version: 1,
+  statuses: [
+    { key: ViableProjectStatus.Draft, intrinsic: IntrinsicStatus.Planned, initial: true, tone: ViableTone.Blue },
+    { key: ViableProjectStatus.Confirmed, intrinsic: IntrinsicStatus.InProgress, tone: ViableTone.Yellow },
+    { key: ViableProjectStatus.Active, intrinsic: IntrinsicStatus.InProgress, tone: ViableTone.Green },
+    { key: ViableProjectStatus.Archived, intrinsic: IntrinsicStatus.Closed, tone: ViableTone.Neutral },
+  ],
+  transitions: [
+    {
+      name: ViableProjectTransition.Confirm,
+      from: [ViableProjectStatus.Draft],
+      to: ViableProjectStatus.Confirmed,
+      explicit: true,
+    },
+    {
+      name: ViableProjectTransition.Activate,
+      from: [ViableProjectStatus.Confirmed],
+      to: ViableProjectStatus.Active,
+    },
+    { name: ViableProjectTransition.Archive, from: '*', to: ViableProjectStatus.Archived, explicit: true },
+    {
+      name: ViableProjectTransition.Reopen,
+      from: [ViableProjectStatus.Archived],
+      to: ViableProjectStatus.Active,
+      explicit: true,
+    },
+  ],
+}
+
+/** A document is written or revised; it has no lifecycle to move through. */
+export const VIABLE_SPEC_FLOW_SCHEMA: StatusFlowSchema = {
+  id: VIABLE_SPEC_FLOW,
+  version: 1,
+  statuses: [
+    { key: ViableSpecStatus.Current, intrinsic: IntrinsicStatus.Closed, initial: true, tone: ViableTone.Neutral },
+  ],
+  transitions: [],
+}
+
+const slot = (
+  category: ViableSpecCategory, format: SpecificationFormat, extra: Partial<SpecificationSlot> = {},
+): SpecificationSlot => ({ category, format, type: VIABLE_SPEC_TYPE, ...extra })
+
+/** The brief a person confirms, and the plan the scaffold draws from it. */
+export const VIABLE_PROJECT_SLOTS: SpecificationSlot[] = [
+  slot(ViableSpecCategory.Specification, SpecificationFormat.Markdown, { required: true }),
+  slot(ViableSpecCategory.Vision, SpecificationFormat.Markdown),
+  slot(ViableSpecCategory.DesignSystem, SpecificationFormat.Markdown),
+  slot(ViableSpecCategory.Scaffold, SpecificationFormat.Json, {
+    revisioned: true, keepRevisions: VIABLE_DESIGN_REVISIONS_KEPT, schema: ScaffoldPlanSchema,
+  }),
+]
+
+/** A story's design — the payload the implementation stage consumes. */
+export const VIABLE_STORY_SLOTS: SpecificationSlot[] = [
+  slot(ViableSpecCategory.Design, SpecificationFormat.Json, {
+    revisioned: true,
+    keepRevisions: VIABLE_DESIGN_REVISIONS_KEPT,
+    schema: StoryDesignSchema,
+    version: STORY_DESIGN_VERSION,
+  }),
+]
+
+const storyLink = (name: ViableRelationship): RelationshipType =>
+  ({ name, from: [VIABLE_STORY_TYPE], to: [VIABLE_STORY_TYPE], single: true })
+
+export const VIABLE_STORY_RELATIONSHIPS: RelationshipType[] = [
+  storyLink(ViableRelationship.Follows),
+  storyLink(ViableRelationship.SharesWidget),
+  storyLink(ViableRelationship.SharesScreen),
+]
+
+export const VIABLE_PROJECT_TYPE_SCHEMA: ProjectTypeSchema = {
+  type: VIABLE_PROJECT_TYPE,
+  kind: WorkcardKind.Project,
+  version: 1,
+  fields: ViableProjectFieldsSchema,
+  flows: [VIABLE_PROJECT_FLOW],
+  intrinsic: IntrinsicPolicy.Primary,
+  specifications: VIABLE_PROJECT_SLOTS,
+  code: VIABLE_PROJECT_CODE,
+  cardTypes: [VIABLE_STORY_TYPE],
+}
+
+export const VIABLE_STORY_TYPE_SCHEMA: WorkcardTypeSchema = {
+  type: VIABLE_STORY_TYPE,
+  kind: WorkcardKind.Card,
+  version: 1,
+  fields: ViableStoryFieldsSchema,
+  flows: [VIABLE_STORY_FLOW],
+  intrinsic: IntrinsicPolicy.Primary,
+  specifications: VIABLE_STORY_SLOTS,
+  relationships: VIABLE_STORY_RELATIONSHIPS,
+  code: VIABLE_STORY_CODE,
+}
+
+export const VIABLE_SPEC_TYPE_SCHEMA: WorkcardTypeSchema = {
+  type: VIABLE_SPEC_TYPE,
+  kind: WorkcardKind.Specification,
+  version: 1,
+  fields: ViableSpecFieldsSchema,
+  flows: [VIABLE_SPEC_FLOW],
+  specifications: [],
+}
+
+const reserved = (type: string, code: WorkcardTypeSchema['code']): WorkcardTypeSchema => ({
+  type,
+  kind: WorkcardKind.Card,
+  version: 1,
+  fields: ViableOpenFieldsSchema,
+  flows: [VIABLE_STORY_FLOW],
+  intrinsic: IntrinsicPolicy.Primary,
+  specifications: [],
+  code,
+})
+
+/** Registered so their prefixes and flow are decided once; not creatable under a project yet. */
+export const VIABLE_RESERVED_TYPE_SCHEMAS: WorkcardTypeSchema[] = [
+  reserved(VIABLE_BUG_TYPE, VIABLE_BUG_CODE),
+  reserved(VIABLE_IMPROVEMENT_TYPE, VIABLE_IMPROVEMENT_CODE),
+  reserved(VIABLE_REQUIREMENT_TYPE, VIABLE_REQUIREMENT_CODE),
+]
+
+/** Every Viable type — what a planning plugin registers. */
+export const VIABLE_TYPE_SCHEMAS: AnyTypeSchema[] = [
+  VIABLE_PROJECT_TYPE_SCHEMA,
+  VIABLE_STORY_TYPE_SCHEMA,
+  VIABLE_SPEC_TYPE_SCHEMA,
+  ...VIABLE_RESERVED_TYPE_SCHEMAS,
+]
+
+/** Every Viable flow — registered beside the types. */
+export const VIABLE_FLOW_SCHEMAS: StatusFlowSchema[] = [
+  VIABLE_PROJECT_FLOW_SCHEMA,
+  VIABLE_STORY_FLOW_SCHEMA,
+  VIABLE_SPEC_FLOW_SCHEMA,
+]

package/src/planning/spec/types.ts

@@ -0,0 +1,22 @@
+import type { Specification, Workcard } from '@owlmeans/planning'
+import type { AgentProject } from '../../ba/types.js'
+
+/** Reading a card's specifications: the current document per category, and the project brief. */
+export interface ViableSpecHelper {
+  /**
+   * The current document of one category among a card's specifications.
+   *
+   * The highest revision wins, then the most recently updated; a category nobody wrote answers
+   * `null`.
+   */
+  currentSpecOf: (specs: readonly Specification[], category: string) => Specification | null
+  /** The body of a category's current document, `''` when there is none. */
+  currentSpecBody: (specs: readonly Specification[], category: string) => string
+  /**
+   * The brief a generator reads, assembled from the project card and its specifications.
+   *
+   * `name` is the card's title and `alias` its code; a brief part nobody wrote is `''`, which is
+   * what every prompt already treats as "not stated".
+   */
+  projectBriefOf: (project: Workcard, specs: readonly Specification[]) => AgentProject
+}

package/src/planning/spec.ts

@@ -0,0 +1,41 @@
+import type { Specification, Workcard } from '@owlmeans/planning'
+import type { AgentProject } from '../ba/types.js'
+import { viableCardHelper } from './card.js'
+import { ViableSpecCategory } from './consts.js'
+import type { ViableSpecHelper } from './spec/types.js'
+
+export const createViableSpecHelper = (): ViableSpecHelper => {
+  const currentSpecOf = (
+    specs: readonly Specification[], category: string,
+  ): Specification | null =>
+    specs
+      .filter(spec => spec.category === category)
+      .reduce<Specification | null>((best, spec) => {
+        if (best == null) return spec
+        const byRevision = (spec.revision ?? 0) - (best.revision ?? 0)
+        if (byRevision !== 0) return byRevision > 0 ? spec : best
+
+        return (spec.updatedAt ?? spec.createdAt) > (best.updatedAt ?? best.createdAt) ? spec : best
+      }, null)
+
+  const currentSpecBody = (specs: readonly Specification[], category: string): string =>
+    currentSpecOf(specs, category)?.body ?? ''
+
+  const projectBriefOf = (project: Workcard, specs: readonly Specification[]): AgentProject => {
+    const { language } = viableCardHelper.projectFieldsOf(project)
+
+    return {
+      name: project.title,
+      ...(project.code != null ? { alias: project.code } : {}),
+      description: project.description ?? '',
+      specification: currentSpecBody(specs, ViableSpecCategory.Specification),
+      designSystem: currentSpecBody(specs, ViableSpecCategory.DesignSystem),
+      vision: currentSpecBody(specs, ViableSpecCategory.Vision),
+      ...(language != null ? { language } : {}),
+    }
+  }
+
+  return { currentSpecOf, currentSpecBody, projectBriefOf }
+}
+
+export const viableSpecHelper = createViableSpecHelper()

package/src/planning/types.ts

@@ -1,13 +1,14 @@
 import type { Card, Project, Specification } from '@owlmeans/planning'
 import type { ProjectArea } from '../areas/consts.js'
 import type { WorkKind } from '../blueprint/consts.js'
-import type { ViableTenancyDecision } from '../areas/tenancy.js'
+import type { ViableTenancyDecision } from '../areas/types.js'
 import type { StoryKind } from '../ba/consts.js'
 import type { ConnectLlm, ConnectTarget } from '../connect/consts.js'
 import type { ProjectOrigin } from '../convert/types.js'
-import type { StoryActor } from '../design/runtime.js'
+import type { StoryActor } from '../design/consts.js'
 import type { StoryWriteInput } from '../metadata/types.js'
 
+// Kept as a type: card fields must satisfy `Record<string, unknown>`, which needs the implicit index signature of a type literal.
 /**
  * What a `viable:project` card keeps under `fields`.
  *
@@ -65,6 +66,7 @@ export interface ViableLandingDecision {
   at: string
 }
 
+// Kept as a type: card fields must satisfy `Record<string, unknown>`, which needs the implicit index signature of a type literal.
 /**
  * What a `viable:user-story` card keeps under `fields`.
  *
@@ -102,7 +104,7 @@ export interface ViableStoryCard extends Card {
 }
 
 /** A document under a Viable card — the brief parts, the scaffold plan, a story design. */
-export type ViableSpecification = Specification
+export interface ViableSpecification extends Specification {}
 
 /**
  * What a develop run hands the metadata store beside the card.
@@ -110,6 +112,4 @@ export type ViableSpecification = Specification
  * The code, the narrative, the primary flag and the landing flag are the CARD's and are never
  * passed separately — a second copy is a second answer. `status` defaults to the card's own.
  */
-export type StoryWriteContent =
-  & Omit<StoryWriteInput, 'code' | 'narrative' | 'primary' | 'landing' | 'status'>
-  & { status?: string }
+export interface StoryWriteContent extends Omit<StoryWriteInput, 'code' | 'narrative' | 'primary' | 'landing' | 'status'> { status?: string }

package/src/preview/consts.ts

@@ -6,4 +6,6 @@ export enum PreviewEventType {
   CaughtError = 'OWLMEANS_PREVIEW_CONSOLE_ERROR',
   PromiseRejection = 'OWLMEANS_PREVIEW_PROMISE_REJECTION',
   FetchError = 'OWLMEANS_PREVIEW_FETCH_ERROR',
+  /** An analytics event a target's web logged through `@owlmeans/log` (browser → manager frame). */
+  Analytics = 'OWLMEANS_PREVIEW_ANALYTICS',
 }

package/src/preview/types.ts

@@ -46,6 +46,19 @@ export interface OwlMeansFetchErrorPayload {
   incidentId?: string
 }
 
+/**
+ * Payload of an analytics event of a target's web — `AnalyticsEvent` of `@owlmeans/log`, as the
+ * target's `viablePreviewPlugin` posts it. Untrusted: it comes from generated code.
+ */
+export interface OwlMeansAnalyticsPayload {
+  event: string
+  scope: string
+  time: number
+  level: 'debug' | 'info' | 'warn' | 'error'
+  message: string
+  data?: unknown
+}
+
 /**
  * Specific message types for each event kind
  */
@@ -65,6 +78,10 @@ export interface OwlMeansCaughtErrorMessage extends OwlMeansPreviewMessage<OwlMe
   type: PreviewEventType.CaughtError
 }
 
+export interface OwlMeansAnalyticsMessage extends OwlMeansPreviewMessage<OwlMeansAnalyticsPayload> {
+  type: PreviewEventType.Analytics
+}
+
 /**
  * Union type for all possible OwlMeans preview messages
  */
@@ -73,9 +90,11 @@ export type OwlMeansPreviewMessages =
   | OwlMeansPromiseRejectionMessage 
   | OwlMeansFetchErrorMessage
   | OwlMeansCaughtErrorMessage
+  | OwlMeansAnalyticsMessage
 
 export type OwlMenasPreviewPayloads = 
   | OwlMeansErrorPayload
   | OwlMeansPromiseRejectionPayload
   | OwlMeansFetchErrorPayload
   | OwlMeansCaughtErrorPayload
+  | OwlMeansAnalyticsPayload

package/src/scaffold/consts.ts

@@ -1,4 +1,6 @@
-import type { BentoFragmentKind, LandingGateFieldKind } from './types.js'
+import type {
+  BentoFragmentKind, LandingAnchor, LandingBand, LandingGateFieldKind, LandingSlot,
+} from './types.js'
 
 /**
  * The shapes a drawn widget can take.
@@ -47,3 +49,65 @@ export const LANDING_GATE_MAX_FIELDS = 3
 
 /** The options a `select` field carries: fewer is no choice, more is a list to browse. */
 export const LANDING_GATE_OPTIONS = { min: 2, max: 6 } as const
+
+/**
+ * The bands of a landing page in the HOUSE ORDER — the order every page draws them in, whichever
+ * of them it carries. `problem` is the problem-and-solution band.
+ */
+export const LANDING_BAND_ORDER: LandingBand[] = [
+  'hero', 'steps', 'features', 'use-cases', 'problem', 'differentiator', 'approach',
+  'testimonials', 'about', 'closing',
+]
+
+/** The bands the guest header menu can jump to, in page order. */
+export const LANDING_ANCHORS: LandingAnchor[] = [
+  'how', 'features', 'use-cases', 'why', 'approach', 'community', 'about',
+]
+
+/** Which band each menu anchor jumps to. */
+export const LANDING_ANCHOR_BAND: Record<LandingAnchor, LandingBand> = {
+  how: 'steps',
+  features: 'features',
+  'use-cases': 'use-cases',
+  why: 'differentiator',
+  approach: 'approach',
+  community: 'testimonials',
+  about: 'about',
+}
+
+/**
+ * The English menu labels an entry falls back to when neither the menu nor the page's own section
+ * label names it. A fallback, never the intended copy: the plan writes labels in the product's
+ * language.
+ */
+export const LANDING_ANCHOR_LABELS: Record<LandingAnchor, string> = {
+  how: 'How it works',
+  features: 'Features',
+  'use-cases': 'Use cases',
+  why: 'Why us',
+  approach: 'How we work',
+  community: 'Reviews',
+  about: 'About',
+}
+
+/** Entries of the guest header menu: fewer is not a menu, more crowds a phone's header. */
+export const LANDING_MENU = { min: 2, max: 4 } as const
+
+/** Cases of the use-cases band; fewer than `min` and the band is not drawn. */
+export const LANDING_USE_CASES = { min: 2, max: 4 } as const
+
+/** Rows of the differentiator's usual-vs-ours contrast; fewer than `min` and no table is drawn. */
+export const LANDING_CONTRAST = { min: 2, max: 3 } as const
+
+/** Principles of the approach band; fewer than `min` and the band is not drawn. */
+export const LANDING_PRINCIPLES = { min: 3, max: 4 } as const
+
+/** Every button or link of a landing page that can open a user story, in page order. */
+export const LANDING_SLOTS: LandingSlot[] = [
+  'hero.cta', 'hero.secondary', 'hero.browse',
+  'useCase.1', 'useCase.2', 'useCase.3', 'useCase.4',
+  'closing.primary', 'closing.secondary', 'closing.link.1', 'closing.link.2',
+]
+
+/** The slots a landing gate replaces: with a usable gate the page draws none of them. */
+export const LANDING_GATE_SLOTS: LandingSlot[] = ['hero.cta', 'hero.secondary', 'closing.primary']

package/src/scaffold/helpers.ts

@@ -1,84 +1,18 @@
-import type { ScaffoldPlan, ScaffoldStoryPlan } 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)
 
-/** Which field the arrow is being followed along. */
-export type ShareKind = 'widget' | 'screen'
+/** @deprecated compat:factory-refactor — use `scaffoldShareHelper.shareGroups(…)` */
+export const shareGroups = (plan: Pick<ScaffoldPlan, 'stories'>, kind: ShareKind = 'widget'): Map<string, string[]> =>
+  scaffoldShareHelper.shareGroups(plan, kind)
 
-const pointerOf = (story: ScaffoldStoryPlan, kind: ShareKind): string | undefined =>
-  kind === 'widget' ? story.sharesWidgetWith : story.sharesScreenWith
+/** @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)
 
-/**
- * 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]))
-
-  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'