@owlmeans/viable-common 0.0.44 → 0.0.46

package/src/moderation/verdict.ts

@@ -0,0 +1,28 @@
+import { ModerationCategory } from './consts.js'
+import type { ModerationAction, ModerationPolicy, ModerationVerdict } from './types.js'
+import type { ModerationVerdictHelper } from './verdict/types.js'
+
+export const createModerationVerdictHelper = (): ModerationVerdictHelper => {
+  const normalizeCategory = (category?: string): ModerationCategory | undefined => {
+    const values = Object.values(ModerationCategory) as string[]
+
+    return category != null && values.includes(category)
+      ? category as ModerationCategory
+      : undefined
+  }
+
+  const decideModeration = (
+    verdict: ModerationVerdict, policy: ModerationPolicy & { entityId?: string } = {}
+  ): ModerationAction => {
+    if (verdict.allowed) return 'allow'
+    if (policy.entityId != null && policy.bypassEntities?.includes(policy.entityId) === true) return 'allow'
+
+    // Defaults to ON: a gate that has to be switched on is a gate that is off in every
+    // environment nobody remembered to configure.
+    return policy.enforce !== false ? 'refuse' : 'shadow'
+  }
+
+  return { normalizeCategory, decideModeration }
+}
+
+export const moderationVerdictHelper = createModerationVerdictHelper()

package/src/planning/card/types.ts

@@ -0,0 +1,44 @@
+import type { Workcard } from '@owlmeans/planning'
+import type { StoryDraft } from '../../areas/types.js'
+import type { UserStory } from '../../ba/types.js'
+import type { StoryDesign } from '../../design/types.js'
+import type { StoryWriteInput } from '../../metadata/types.js'
+import type {
+  StoryWriteContent, ViableProjectCard, ViableProjectFields, ViableStoryCard, ViableStoryFields,
+} from '../types.js'
+
+/** Reading Viable's planning cards — a project, a user story — and what a write carries. */
+export interface ViableCardHelper {
+  /** A `viable:project` card — kind AND type, since a foreign provider may share either alone. */
+  isViableProject: (card?: Workcard | null) => card is ViableProjectCard
+  /** A `viable:user-story` card. */
+  isViableStory: (card?: Workcard | null) => card is ViableStoryCard
+  /** Whether a write came from a person (`web`, `connect`) rather than the platform's own runs. */
+  isUserChannel: (channel?: string | null) => boolean
+  projectFieldsOf: (card: Workcard) => ViableProjectFields
+  /**
+   * A story card's fields, with the two required ones always answered.
+   *
+   * An absent area reads as `guest` — the area that guards nothing — and an absent primary flag as
+   * `false`, so a reader never branches on a card written by a store that dropped them.
+   */
+  storyFieldsOf: (card: Workcard) => ViableStoryFields
+  /** The draft shape the analysis prompts and moderation take, from a card. */
+  storyDraftOf: (card: Workcard) => StoryDraft
+  /**
+   * The aggregate the coders take, for a story CARD.
+   *
+   * The card wins on the narrative, the code, the area and the actor — a person may have changed any
+   * of them since the design was written. The design supplies what only it knows: the entities and
+   * the screens. Without a design the aggregate has no screens yet.
+   */
+  userStoryOf: (card: Workcard, design?: StoryDesign | null) => UserStory
+  /**
+   * What the metadata store writes to `docs/stories/<code>.md`, from the card and a run's content.
+   *
+   * The CODE is the target's only story identifier — a card id never reaches a target file — so a
+   * story card without one is refused rather than filed under its id. The landing flag is carried
+   * only when it is set, so every other story's frontmatter keeps the shape it always had.
+   */
+  storyWriteInputOf: (card: Workcard, content: StoryWriteContent) => StoryWriteInput
+}

package/src/planning/card.ts

@@ -0,0 +1,77 @@
+import { WorkcardKind } from '@owlmeans/planning'
+import type { Workcard } from '@owlmeans/planning'
+import { ProjectArea } from '../areas/consts.js'
+import type { StoryDraft } from '../areas/types.js'
+import type { UserStory } from '../ba/types.js'
+import { storyDesignHelper } from '../design/story.js'
+import type { StoryDesign } from '../design/types.js'
+import type { StoryWriteInput } from '../metadata/types.js'
+import { VIABLE_PROJECT_TYPE, VIABLE_STORY_TYPE, VIABLE_USER_CHANNELS } from './consts.js'
+import { ProjectStoryMissconfigured } from './errors.js'
+import type {
+  StoryWriteContent, ViableProjectCard, ViableProjectFields, ViableStoryCard, ViableStoryFields,
+} from './types.js'
+import type { ViableCardHelper } from './card/types.js'
+
+export const createViableCardHelper = (): ViableCardHelper => {
+  const isViableProject = (card?: Workcard | null): card is ViableProjectCard =>
+    card != null && card.kind === WorkcardKind.Project && card.type === VIABLE_PROJECT_TYPE
+
+  const isViableStory = (card?: Workcard | null): card is ViableStoryCard =>
+    card != null && card.kind === WorkcardKind.Card && card.type === VIABLE_STORY_TYPE
+
+  const isUserChannel = (channel?: string | null): boolean =>
+    channel != null && VIABLE_USER_CHANNELS.includes(channel)
+
+  const projectFieldsOf = (card: Workcard): ViableProjectFields =>
+    (card.fields ?? {}) as ViableProjectFields
+
+  const storyFieldsOf = (card: Workcard): ViableStoryFields => {
+    const fields = (card.fields ?? {}) as Partial<ViableStoryFields>
+
+    return { ...fields, area: fields.area ?? ProjectArea.Guest, primary: fields.primary === true }
+  }
+
+  const storyDraftOf = (card: Workcard): StoryDraft =>
+    ({ story: card.title, area: storyFieldsOf(card).area })
+
+  const userStoryOf = (card: Workcard, design?: StoryDesign | null): UserStory => {
+    const fields = storyFieldsOf(card)
+    const base: UserStory = design != null
+      ? storyDesignHelper.userStoryOfDesign(design)
+      : { story: card.title, area: fields.area, entity: null as unknown as string, entities: [], screens: [] }
+    const code = card.code ?? base.code
+
+    return {
+      ...base,
+      story: card.title,
+      ...(code != null ? { code } : {}),
+      area: fields.area,
+      ...(fields.actor != null ? { actor: fields.actor } : {}),
+    }
+  }
+
+  const storyWriteInputOf = (card: Workcard, content: StoryWriteContent): StoryWriteInput => {
+    if (card.code == null || card.code === '') {
+      throw new ProjectStoryMissconfigured('no-code')
+    }
+    const { status, ...rest } = content
+    const fields = storyFieldsOf(card)
+
+    return {
+      ...rest,
+      code: card.code,
+      narrative: card.title,
+      status: status ?? card.status,
+      primary: fields.primary,
+      ...(fields.landing === true ? { landing: true } : {}),
+    }
+  }
+
+  return {
+    isViableProject, isViableStory, isUserChannel, projectFieldsOf, storyFieldsOf, storyDraftOf, userStoryOf,
+    storyWriteInputOf,
+  }
+}
+
+export const viableCardHelper = createViableCardHelper()

package/src/planning/helpers.ts

@@ -1,136 +1,48 @@
-import { WorkcardKind } from '@owlmeans/planning'
 import type { Specification, Workcard } from '@owlmeans/planning'
-import { ProjectArea } from '../areas/consts.js'
 import type { StoryDraft } from '../areas/types.js'
 import type { AgentProject, UserStory } from '../ba/types.js'
-import { userStoryOfDesign } from '../design/helpers.js'
 import type { StoryDesign } from '../design/types.js'
 import type { StoryWriteInput } from '../metadata/types.js'
-import {
-  VIABLE_PROJECT_TYPE, VIABLE_STORY_TYPE, VIABLE_USER_CHANNELS, ViableSpecCategory,
-} from './consts.js'
-import { ProjectStoryMissconfigured } from './errors.js'
+import { viableCardHelper } from './card.js'
+import { viableSpecHelper } from './spec.js'
 import type {
   StoryWriteContent, ViableProjectCard, ViableProjectFields, ViableStoryCard, ViableStoryFields,
 } from './types.js'
 
-/** A `viable:project` card — kind AND type, since a foreign provider may share either alone. */
-export const isViableProject = (card?: Workcard | null): card is ViableProjectCard =>
-  card != null && card.kind === WorkcardKind.Project && card.type === VIABLE_PROJECT_TYPE
+/** @deprecated compat:factory-refactor — use `viableCardHelper.isViableProject(…)` */
+export const isViableProject = (card?: Workcard | null): card is ViableProjectCard => viableCardHelper.isViableProject(card)
 
-/** A `viable:user-story` card. */
-export const isViableStory = (card?: Workcard | null): card is ViableStoryCard =>
-  card != null && card.kind === WorkcardKind.Card && card.type === VIABLE_STORY_TYPE
+/** @deprecated compat:factory-refactor — use `viableCardHelper.isViableStory(…)` */
+export const isViableStory = (card?: Workcard | null): card is ViableStoryCard => viableCardHelper.isViableStory(card)
 
-/** Whether a write came from a person (`web`, `connect`) rather than the platform's own runs. */
-export const isUserChannel = (channel?: string | null): boolean =>
-  channel != null && VIABLE_USER_CHANNELS.includes(channel)
+/** @deprecated compat:factory-refactor — use `viableCardHelper.isUserChannel(…)` */
+export const isUserChannel = (channel?: string | null): boolean => viableCardHelper.isUserChannel(channel)
 
-export const projectFieldsOf = (card: Workcard): ViableProjectFields =>
-  (card.fields ?? {}) as ViableProjectFields
+/** @deprecated compat:factory-refactor — use `viableCardHelper.projectFieldsOf(…)` */
+export const projectFieldsOf = (card: Workcard): ViableProjectFields => viableCardHelper.projectFieldsOf(card)
 
-/**
- * A story card's fields, with the two required ones always answered.
- *
- * An absent area reads as `guest` — the area that guards nothing — and an absent primary flag as
- * `false`, so a reader never branches on a card written by a store that dropped them.
- */
-export const storyFieldsOf = (card: Workcard): ViableStoryFields => {
-  const fields = (card.fields ?? {}) as Partial<ViableStoryFields>
+/** @deprecated compat:factory-refactor — use `viableCardHelper.storyFieldsOf(…)` */
+export const storyFieldsOf = (card: Workcard): ViableStoryFields => viableCardHelper.storyFieldsOf(card)
 
-  return { ...fields, area: fields.area ?? ProjectArea.Guest, primary: fields.primary === true }
-}
+/** @deprecated compat:factory-refactor — use `viableCardHelper.storyDraftOf(…)` */
+export const storyDraftOf = (card: Workcard): StoryDraft => viableCardHelper.storyDraftOf(card)
 
-/** The draft shape the analysis prompts and moderation take, from a card. */
-export const storyDraftOf = (card: Workcard): StoryDraft =>
-  ({ story: card.title, area: storyFieldsOf(card).area })
+/** @deprecated compat:factory-refactor — use `viableCardHelper.userStoryOf(…)` */
+export const userStoryOf = (card: Workcard, design?: StoryDesign | null): UserStory =>
+  viableCardHelper.userStoryOf(card, design)
 
-/**
- * The aggregate the coders take, for a story CARD.
- *
- * The card wins on the narrative, the code, the area and the actor — a person may have changed any
- * of them since the design was written. The design supplies what only it knows: the entities and
- * the screens. Without a design the aggregate has no screens yet.
- */
-export const userStoryOf = (card: Workcard, design?: StoryDesign | null): UserStory => {
-  const fields = storyFieldsOf(card)
-  const base: UserStory = design != null
-    ? userStoryOfDesign(design)
-    : { story: card.title, area: fields.area, entity: null as unknown as string, entities: [], screens: [] }
-  const code = card.code ?? base.code
+/** @deprecated compat:factory-refactor — use `viableSpecHelper.currentSpecOf(…)` */
+export const currentSpecOf = (specs: readonly Specification[], category: string): Specification | null =>
+  viableSpecHelper.currentSpecOf(specs, category)
 
-  return {
-    ...base,
-    story: card.title,
-    ...(code != null ? { code } : {}),
-    area: fields.area,
-    ...(fields.actor != null ? { actor: fields.actor } : {}),
-  }
-}
-
-/**
- * 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`.
- */
-export 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)
-
-/** The body of a category's current document, `''` when there is none. */
+/** @deprecated compat:factory-refactor — use `viableSpecHelper.currentSpecBody(…)` */
 export const currentSpecBody = (specs: readonly Specification[], category: string): string =>
-  currentSpecOf(specs, category)?.body ?? ''
-
-/**
- * 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".
- */
-export const projectBriefOf = (project: Workcard, specs: readonly Specification[]): AgentProject => {
-  const { language } = 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 } : {}),
-  }
-}
+  viableSpecHelper.currentSpecBody(specs, category)
 
-/**
- * What the metadata store writes to `docs/stories/<code>.md`, from the card and a run's content.
- *
- * The CODE is the target's only story identifier — a card id never reaches a target file — so a
- * story card without one is refused rather than filed under its id. The landing flag is carried
- * only when it is set, so every other story's frontmatter keeps the shape it always had.
- */
-export const storyWriteInputOf = (card: Workcard, content: StoryWriteContent): StoryWriteInput => {
-  if (card.code == null || card.code === '') {
-    throw new ProjectStoryMissconfigured('no-code')
-  }
-  const { status, ...rest } = content
-  const fields = storyFieldsOf(card)
+/** @deprecated compat:factory-refactor — use `viableSpecHelper.projectBriefOf(…)` */
+export const projectBriefOf = (project: Workcard, specs: readonly Specification[]): AgentProject =>
+  viableSpecHelper.projectBriefOf(project, specs)
 
-  return {
-    ...rest,
-    code: card.code,
-    narrative: card.title,
-    status: status ?? card.status,
-    primary: fields.primary,
-    ...(fields.landing === true ? { landing: true } : {}),
-  }
-}
+/** @deprecated compat:factory-refactor — use `viableCardHelper.storyWriteInputOf(…)` */
+export const storyWriteInputOf = (card: Workcard, content: StoryWriteContent): StoryWriteInput =>
+  viableCardHelper.storyWriteInputOf(card, content)

package/src/planning/index.ts

@@ -1,6 +1,11 @@
 export * from './consts.js'
 export * from './errors.js'
 export * from './schemas.js'
+export * from './card.js'
+export * from './spec.js'
 export * from './helpers.js'
 export * from './landing.js'
 export type * from './types.js'
+export type * from './card/types.js'
+export type * from './spec/types.js'
+export type * from './landing/types.js'

package/src/planning/landing/types.ts

@@ -0,0 +1,15 @@
+/** The landing sentence a landing-gate story's narrative carries. */
+export interface LandingSentenceHelper {
+  /** Whether a narrative already carries the landing sentence, whatever whitespace surrounds it. */
+  hasLandingSentence: (title: string) => boolean
+  /**
+   * 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.
+   */
+  withLandingSentence: (title: string) => string
+}

package/src/planning/landing.ts

@@ -1,30 +1,33 @@
 import { TITLE_MAX } from '@owlmeans/planning'
 import { LANDING_STORY_SENTENCE } from './consts.js'
+import type { LandingSentenceHelper } from './landing/types.js'
 
-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

@@ -198,7 +198,7 @@ export const VIABLE_SPEC_FLOW_SCHEMA: StatusFlowSchema = {
   transitions: [],
 }
 
-export const slot = (
+const slot = (
   category: ViableSpecCategory, format: SpecificationFormat, extra: Partial<SpecificationSlot> = {},
 ): SpecificationSlot => ({ category, format, type: VIABLE_SPEC_TYPE, ...extra })
 
@@ -222,7 +222,7 @@ export const VIABLE_STORY_SLOTS: SpecificationSlot[] = [
   }),
 ]
 
-export const storyLink = (name: ViableRelationship): RelationshipType =>
+const storyLink = (name: ViableRelationship): RelationshipType =>
   ({ name, from: [VIABLE_STORY_TYPE], to: [VIABLE_STORY_TYPE], single: true })
 
 export const VIABLE_STORY_RELATIONSHIPS: RelationshipType[] = [
@@ -264,7 +264,7 @@ export const VIABLE_SPEC_TYPE_SCHEMA: WorkcardTypeSchema = {
   specifications: [],
 }
 
-export const reserved = (type: string, code: WorkcardTypeSchema['code']): WorkcardTypeSchema => ({
+const reserved = (type: string, code: WorkcardTypeSchema['code']): WorkcardTypeSchema => ({
   type,
   kind: WorkcardKind.Card,
   version: 1,

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

@@ -8,6 +8,7 @@ import type { ProjectOrigin } from '../convert/types.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/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']