@anthusai/papyrus 0.0.0 → 1.0.0-next.10

package/lib/console-web-context.ts

@@ -0,0 +1,118 @@
+import type { PapyrusWebUiContext } from "./papyrus-web-locations";
+
+export const CONSOLE_WEB_CONTEXT_MESSAGE_KIND = "console_web_context";
+
+export type ConsoleWebContextEvent = "session_start" | "navigation";
+
+export type FormattedConsoleWebContext = {
+  visibleContent: string;
+  summary: string;
+  agentInstructions: string;
+};
+
+export function webUiContextKey(webUi: PapyrusWebUiContext): string {
+  return [
+    webUi.papyrusLocationUri,
+    webUi.webPath,
+    webUi.papyrusObjectUri ?? "",
+    webUi.viewMode ?? "",
+  ].join("|");
+}
+
+export function formatConsoleWebContextMessage(
+  webUi: PapyrusWebUiContext,
+  event: ConsoleWebContextEvent,
+): FormattedConsoleWebContext {
+  const locationUri = webUi.papyrusLocationUri.trim();
+  const webPath = webUi.webPath.trim();
+  const objectUri = webUi.papyrusObjectUri?.trim() ?? "";
+  const label = webUi.label?.trim() ?? "";
+  const tab = webUi.newsroomTab?.trim() ?? "";
+  const viewMode = webUi.viewMode?.trim() ?? "";
+
+  const headline = event === "session_start"
+    ? "Console session started on this page."
+    : "You navigated to a new page in the newsroom.";
+
+  const visibleLines = [
+    headline,
+    "",
+    locationUri ? `Papyrus location: ${locationUri}` : null,
+    webPath ? `Web path: ${webPath}` : null,
+    objectUri ? `Focused object: ${objectUri}` : null,
+    label ? `Label: ${label}` : null,
+    tab ? `Desk: ${tab}` : null,
+    viewMode ? `View: ${viewMode}` : null,
+  ].filter((line): line is string => Boolean(line));
+
+  const agentLines = [
+    "Papyrus web UI context for this console thread:",
+    locationUri ? `- papyrus_location_uri: ${locationUri}` : null,
+    webPath ? `- web_path: ${webPath}` : null,
+    objectUri ? `- focused_object_uri: ${objectUri}` : null,
+    label ? `- label: ${label}` : null,
+    viewMode ? `- view_mode: ${viewMode}` : null,
+    tab ? `- newsroom_tab: ${tab}` : null,
+    "",
+    "Use execute_tactus with papyrus.web.current_location{} to re-read this snapshot.",
+    "Use papyrus.web.navigate{ uri = \"papyrus://...\" } to move the browser when appropriate.",
+  ].filter((line): line is string => line !== null);
+
+  if (objectUri.startsWith("papyrus://reference/")) {
+    const referenceId = objectUri.slice("papyrus://reference/".length).trim();
+    if (referenceId) {
+      agentLines.push(
+        "",
+        `The user is viewing reference detail (${referenceId}). For questions about "this reference", the open page, or what they are looking at, do not ask them to paste the reference.`,
+        `First call execute_tactus with: return papyrus.Reference.get{ id = "${referenceId}" } (lineage ids from the URL resolve to the current version).`,
+        `Then call: return papyrus.knowledge.query{ semanticQuery = "Summarize the main claims, methods, and results.", anchors = { { uri = "papyrus://reference/${referenceId}" } } }`,
+        "Use double-quoted Lua strings only. Do not use JS parentheses, string.match, or multi-line Lua beyond simple return statements.",
+      );
+    }
+  }
+
+  const summaryParts = [label, tab, viewMode === "detail" ? "detail" : "index"].filter(Boolean);
+  return {
+    visibleContent: visibleLines.join("\n"),
+    summary: summaryParts.length
+      ? `Page context: ${summaryParts.join(" · ")}`
+      : "Page context updated",
+    agentInstructions: agentLines.join("\n"),
+  };
+}
+
+export function readConsoleAgentInstructionsFromMessageMetadata(metadata: unknown): string | null {
+  if (!metadata || typeof metadata !== "object") return null;
+  const record = metadata as Record<string, unknown>;
+  const consoleMeta = record.console;
+  if (!consoleMeta || typeof consoleMeta !== "object") return null;
+  const instructions = (consoleMeta as Record<string, unknown>).agentInstructions;
+  return typeof instructions === "string" && instructions.trim() ? instructions.trim() : null;
+}
+
+export function readConsoleWebUiFromMessageMetadata(metadata: unknown): PapyrusWebUiContext | null {
+  if (!metadata || typeof metadata !== "object") return null;
+  const record = metadata as Record<string, unknown>;
+  const consoleMeta = record.console;
+  if (!consoleMeta || typeof consoleMeta !== "object") return null;
+  const webUi = (consoleMeta as Record<string, unknown>).webUi;
+  if (!webUi || typeof webUi !== "object") return null;
+  const entry = webUi as Record<string, unknown>;
+  const webPath = typeof entry.webPath === "string" ? entry.webPath : "";
+  const papyrusLocationUri = typeof entry.papyrusLocationUri === "string" ? entry.papyrusLocationUri : "";
+  if (!webPath && !papyrusLocationUri) return null;
+  return {
+    webPath,
+    papyrusLocationUri,
+    papyrusObjectUri: typeof entry.papyrusObjectUri === "string" ? entry.papyrusObjectUri : null,
+    newsroomTab: typeof entry.newsroomTab === "string" ? entry.newsroomTab : null,
+    viewMode: entry.viewMode === "index" || entry.viewMode === "detail" ? entry.viewMode : null,
+    indexFilters: entry.indexFilters && typeof entry.indexFilters === "object"
+      ? Object.fromEntries(
+        Object.entries(entry.indexFilters as Record<string, unknown>)
+          .filter(([, value]) => typeof value === "string" && value.trim()),
+      ) as Record<string, string>
+      : null,
+    label: typeof entry.label === "string" ? entry.label : null,
+  };
+}

package/lib/content-actions-client.ts

@@ -0,0 +1,98 @@
+import { generateClient } from "aws-amplify/data";
+import type { Schema } from "../amplify/data/resource";
+
+export type ContentActionError = { code: string; message: string; line: number | null };
+
+export type DeriveMarkusInput = { frontMatterYaml: string | null; bodyMarkus: string; includeIr?: boolean };
+export type SaveItemDraftInput = {
+  id: string | null;
+  type: string;
+  slug: string;
+  section: string | null;
+  frontMatterYaml: string | null;
+  bodyMarkus: string;
+  aliases: string[];
+  expectedContentHash: string | null;
+};
+
+export type DeriveMarkusResult = { ok: true; bodyIrBytes: number; bodyIr?: unknown; errors: [] };
+export type SavedItemSummary = {
+  id: string;
+  contentHash: string;
+  status: string;
+  slug: string;
+  versionNumber: number | null;
+};
+export type SaveItemDraftResult = { ok: true; item: SavedItemSummary };
+export type PublishItemResult = { ok: true; changed: boolean; publishedId: string; versionNumber: number | null };
+export type UnpublishItemResult = { ok: true; changed: boolean };
+
+export class ContentActionFailure extends Error {
+  readonly errors: ContentActionError[];
+
+  constructor(errors: ContentActionError[]) {
+    super(errors.map((error) => error.message).join("; ") || "Content action failed");
+    this.name = "ContentActionFailure";
+    this.errors = errors;
+  }
+}
+
+type GraphqlEnvelope = { data?: unknown; errors?: { message?: string }[] | null };
+
+export type ContentActionsTransport = {
+  queries: { deriveMarkus: (args: { input: string }, options: { authMode: "userPool" }) => Promise<GraphqlEnvelope> };
+  mutations: {
+    saveItemDraft: (args: { input: string }, options: { authMode: "userPool" }) => Promise<GraphqlEnvelope>;
+    publishItem: (args: { input: string }, options: { authMode: "userPool" }) => Promise<GraphqlEnvelope>;
+    unpublishItem: (args: { input: string }, options: { authMode: "userPool" }) => Promise<GraphqlEnvelope>;
+  };
+};
+
+const USER_POOL = { authMode: "userPool" } as const;
+
+function parseActionResponse<T>(envelope: GraphqlEnvelope): T {
+  if (envelope.errors && envelope.errors.length > 0) {
+    throw new Error(envelope.errors.map((error) => error.message ?? "GraphQL error").join("; "));
+  }
+  const raw = envelope.data;
+  const parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("The content action returned no data.");
+  }
+  const response = parsed as { ok?: boolean; errors?: ContentActionError[] };
+  if (response.ok !== true) {
+    throw new ContentActionFailure(response.errors ?? []);
+  }
+  return parsed as T;
+}
+
+export function createContentActionsClient(transport: ContentActionsTransport) {
+  return {
+    async deriveMarkus(input: DeriveMarkusInput): Promise<DeriveMarkusResult> {
+      return parseActionResponse(await transport.queries.deriveMarkus({ input: JSON.stringify(input) }, USER_POOL));
+    },
+    async saveItemDraft(input: SaveItemDraftInput): Promise<SaveItemDraftResult> {
+      return parseActionResponse(await transport.mutations.saveItemDraft({ input: JSON.stringify(input) }, USER_POOL));
+    },
+    async publishItem(id: string): Promise<PublishItemResult> {
+      return parseActionResponse(await transport.mutations.publishItem({ input: JSON.stringify({ id }) }, USER_POOL));
+    },
+    async unpublishItem(id: string): Promise<UnpublishItemResult> {
+      return parseActionResponse(await transport.mutations.unpublishItem({ input: JSON.stringify({ id }) }, USER_POOL));
+    },
+  };
+}
+
+let defaultClient: ReturnType<typeof createContentActionsClient> | null = null;
+
+function contentActionsClient() {
+  if (!defaultClient) {
+    defaultClient = createContentActionsClient(generateClient<Schema>() as unknown as ContentActionsTransport);
+  }
+  return defaultClient;
+}
+
+export const deriveMarkus = (input: DeriveMarkusInput) => contentActionsClient().deriveMarkus(input);
+export const saveItemDraft = (input: SaveItemDraftInput) => contentActionsClient().saveItemDraft(input);
+export const publishItem = (id: string) => contentActionsClient().publishItem(id);
+export const unpublishItem = (id: string) => contentActionsClient().unpublishItem(id);

package/lib/content-actions-demo.ts

@@ -0,0 +1,190 @@
+import { ContentActionFailure } from "./content-actions-client";
+import type {
+  DeriveMarkusInput,
+  DeriveMarkusResult,
+  PublishItemResult,
+  SaveItemDraftInput,
+  SaveItemDraftResult,
+  UnpublishItemResult,
+} from "./content-actions-client";
+import {
+  createDemoArticleRecords,
+  demoContentHash,
+  type DemoArticleRecord,
+} from "./newsroom-demo-articles";
+import { sourceLineOffset, type ArticlesBackend, type EditableArticle, type NewsroomArticleRow } from "./newsroom-articles";
+
+function titleFromYaml(frontMatterYaml: string | null, fallback: string): string {
+  for (const line of (frontMatterYaml ?? "").split("\n")) {
+    const match = /^title\s*:\s*(.*)$/.exec(line);
+    if (match && match[1].trim()) return match[1].trim().replace(/^["']|["']$/g, "");
+  }
+  return fallback;
+}
+
+const DEMO_IMAGE_DIRECTIVE = /^::image\{([^}]*)\}$/;
+
+function demoAttribute(attributes: string, name: string): string {
+  const match = new RegExp(`${name}="([^"]*)"`).exec(attributes);
+  return match ? match[1] : "";
+}
+
+function demoEnvelope(bodyMarkus: string) {
+  const images: Record<string, Record<string, unknown>> = {};
+  const children = bodyMarkus
+    .split(/\n{2,}/)
+    .map((block) => block.trim())
+    .filter(Boolean)
+    .map((block) => {
+      const heading = /^(#{1,6})\s+(.*)$/.exec(block);
+      if (heading) {
+        return { type: "heading", level: heading[1].length, inline: [{ type: "text", text: heading[2] }], line: null };
+      }
+      const image = DEMO_IMAGE_DIRECTIVE.exec(block);
+      if (image) {
+        const token = `PAPYRUSMARKUP${String(Object.keys(images).length + 1).padStart(5, "0")}END`;
+        images[token] = {
+          src: demoAttribute(image[1], "src"),
+          alt: demoAttribute(image[1], "alt"),
+          layout: demoAttribute(image[1], "layout") || null,
+        };
+        return { type: "paragraph", inline: [{ type: "text", text: token }], line: null };
+      }
+      return { type: "paragraph", inline: [{ type: "text", text: block }], line: null };
+    });
+  return {
+    schemaVersion: 1,
+    markus: { version: "demo", irSchemaVersion: 1 },
+    document: { type: "document", schema_version: 1, front_matter: {}, children },
+    papyrus: { images, citations: {}, citationLists: {}, entries: {}, bibliography: [] },
+  };
+}
+
+export function createDemoArticlesBackend(): ArticlesBackend {
+  const records = new Map<string, DemoArticleRecord>(createDemoArticleRecords().map((record) => [record.id, record]));
+  let created = 0;
+
+  const requireRecord = (id: string): DemoArticleRecord => {
+    const record = records.get(id);
+    if (!record) throw new ContentActionFailure([{ code: "not-found", message: "That article was not found.", line: null }]);
+    return record;
+  };
+
+  return {
+    actions: {
+      async deriveMarkus(input: DeriveMarkusInput): Promise<DeriveMarkusResult> {
+        const lines = input.bodyMarkus.split("\n");
+        const invalidIndex = lines.findIndex((line) => line.includes(":::nope"));
+        if (invalidIndex >= 0) {
+          throw new ContentActionFailure([
+            { code: "markus-validation", message: 'Unknown directive "nope".', line: invalidIndex + 1 + sourceLineOffset(input.frontMatterYaml) },
+          ]);
+        }
+        const envelope = demoEnvelope(input.bodyMarkus);
+        return {
+          ok: true,
+          bodyIrBytes: JSON.stringify(envelope).length,
+          ...(input.includeIr ? { bodyIr: envelope } : {}),
+          errors: [],
+        };
+      },
+      async saveItemDraft(input: SaveItemDraftInput): Promise<SaveItemDraftResult> {
+        const existing = input.id ? requireRecord(input.id) : null;
+        if (existing && input.expectedContentHash !== null && input.expectedContentHash !== existing.contentHash) {
+          throw new ContentActionFailure([
+            { code: "conflict", message: "The item changed since it was loaded.", line: null },
+          ]);
+        }
+        if (existing && existing.everPublished && existing.slug !== input.slug) {
+          throw new ContentActionFailure([
+            { code: "slug-locked", message: "The slug cannot change once the item has been published.", line: null },
+          ]);
+        }
+        const id = existing?.id ?? `demo-article-new-${(created += 1)}`;
+        const title = titleFromYaml(input.frontMatterYaml, input.slug);
+        const frontMatterYaml = input.frontMatterYaml ?? "";
+        const record: DemoArticleRecord = {
+          id,
+          type: input.type,
+          slug: input.slug,
+          section: input.section,
+          title,
+          status: existing?.status ?? "draft",
+          frontMatterYaml,
+          bodyMarkus: input.bodyMarkus,
+          contentHash: demoContentHash(frontMatterYaml, input.bodyMarkus),
+          publishedContentHash: existing?.publishedContentHash ?? null,
+          versionNumber: existing?.versionNumber ?? null,
+          everPublished: existing?.everPublished ?? false,
+          updatedAt: new Date().toISOString(),
+        };
+        records.set(id, record);
+        return {
+          ok: true,
+          item: {
+            id,
+            contentHash: record.contentHash,
+            status: record.status,
+            slug: record.slug,
+            versionNumber: record.versionNumber,
+          },
+        };
+      },
+      async publishItem(id: string): Promise<PublishItemResult> {
+        const record = requireRecord(id);
+        const changed = record.status !== "published" || record.publishedContentHash !== record.contentHash;
+        const versionNumber = changed ? (record.versionNumber ?? 0) + 1 : record.versionNumber;
+        records.set(id, {
+          ...record,
+          status: "published",
+          everPublished: true,
+          publishedContentHash: record.contentHash,
+          versionNumber,
+          updatedAt: new Date().toISOString(),
+        });
+        return { ok: true, changed, publishedId: `published-${id}`, versionNumber };
+      },
+      async unpublishItem(id: string): Promise<UnpublishItemResult> {
+        const record = requireRecord(id);
+        const changed = record.status === "published";
+        records.set(id, {
+          ...record,
+          status: "draft",
+          publishedContentHash: null,
+          updatedAt: new Date().toISOString(),
+        });
+        return { ok: true, changed };
+      },
+    },
+    async listRows(): Promise<NewsroomArticleRow[]> {
+      return [...records.values()]
+        .map((record) => ({
+          id: record.id,
+          type: record.type,
+          slug: record.slug,
+          section: record.section,
+          title: record.title || record.slug,
+          status: record.status,
+          pending: record.status === "published" && record.publishedContentHash !== record.contentHash,
+          updatedAt: record.updatedAt,
+        }))
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    },
+    async loadArticle(id: string): Promise<EditableArticle> {
+      const record = requireRecord(id);
+      return {
+        id: record.id,
+        type: record.type,
+        section: record.section,
+        slug: record.slug,
+        frontMatterYaml: record.frontMatterYaml,
+        bodyMarkus: record.bodyMarkus,
+        contentHash: record.contentHash,
+        status: record.status,
+        versionNumber: record.versionNumber,
+        aliases: [],
+        everPublished: record.everPublished,
+      };
+    },
+  };
+}

package/lib/content-load-timing.ts

@@ -0,0 +1,23 @@
+type ContentLoadMetadata = Record<string, string | number | boolean | null | undefined>;
+
+export function isContentLoadTimingEnabled(): boolean {
+  return process.env.PAPYRUS_CONTENT_LOAD_TIMING === "1";
+}
+
+export async function withContentLoadTiming<T>(
+  label: string,
+  metadata: ContentLoadMetadata,
+  work: () => Promise<T>,
+): Promise<T> {
+  if (!isContentLoadTimingEnabled()) {
+    return work();
+  }
+
+  const started = performance.now();
+  try {
+    return await work();
+  } finally {
+    const elapsedMs = Math.round(performance.now() - started);
+    console.info(`[papyrus-content-load] ${label} ${JSON.stringify({ ...metadata, ms: elapsedMs })}`);
+  }
+}

package/lib/content-repository.ts

@@ -0,0 +1,43 @@
+import type { ContentRepository } from "./content-types";
+import { graphqlContentRepository } from "./graphql-content-repository";
+import { getLayoutScenario } from "./layout-scenarios";
+import { assertContentSourceMatchesEnv } from "./site-env";
+
+assertContentSourceMatchesEnv();
+
+export const contentRepository: ContentRepository = {
+  loadEditionContent({ scenarioId, editionDate, editionSlug } = {}) {
+    if (scenarioId) return getLayoutScenario(scenarioId);
+    return graphqlContentRepository.loadEditionContent({ editionDate, editionSlug });
+  },
+  getLatestPublishedEdition() {
+    return graphqlContentRepository.getLatestPublishedEdition();
+  },
+  getFirstPublishedEdition() {
+    return graphqlContentRepository.getFirstPublishedEdition();
+  },
+  listPublishedEditions(options) {
+    return graphqlContentRepository.listPublishedEditions(options);
+  },
+  getArticle(slug: string) {
+    return graphqlContentRepository.getArticle(slug);
+  },
+  getEditionArticle(options) {
+    return graphqlContentRepository.getEditionArticle(options);
+  },
+  getEditionItem(options) {
+    return graphqlContentRepository.getEditionItem(options);
+  },
+  listArticleSlugs() {
+    return graphqlContentRepository.listArticleSlugs();
+  },
+};
+
+export function getScenarioIdParam(scenario: string | string[] | null | undefined): string | null {
+  if (Array.isArray(scenario)) return scenario[0] ?? null;
+  return scenario ?? null;
+}
+
+export function isGraphQLContentSource(): boolean {
+  return true;
+}

package/lib/content-source-context.ts

@@ -0,0 +1,26 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { getContentSource, type ContentSource } from "./site-env";
+
+export type ContentSourceContext = {
+  source: ContentSource;
+  /** Request-scoped data client (drafts mode: carries the visitor's session cookies). */
+  client?: unknown;
+};
+
+const contentSourceStorage = new AsyncLocalStorage<ContentSourceContext>();
+
+export function runWithContentSource<T>(
+  source: ContentSource,
+  operation: () => Promise<T>,
+  client?: unknown,
+): Promise<T> {
+  return contentSourceStorage.run({ source, client }, operation);
+}
+
+export function currentRequestClient<T>(): T | undefined {
+  return contentSourceStorage.getStore()?.client as T | undefined;
+}
+
+export function currentContentSource(): ContentSource {
+  return contentSourceStorage.getStore()?.source ?? getContentSource();
+}

package/lib/content-types.ts

@@ -0,0 +1,104 @@
+import type { Article, ArticleVideoAsset } from "./articles";
+import type { EditionLayoutPlan } from "./layout-plan";
+import type { PublicationItem } from "./publication-items";
+
+export type ContentSource = "scenario" | "graphql";
+
+import type { PretextLayout } from "./renderer-config";
+
+/** @deprecated Use PretextLayout from lib/renderer-config.ts */
+export type EditionPresentationFormat = PretextLayout;
+
+export type EditionSection = {
+  key: string;
+  label: string;
+  description?: string | null;
+  itemIds: string[];
+};
+
+export type NewsDeskCategoryTreeNode = {
+  id: string;
+  categorySetId: string;
+  categoryKey: string;
+  parentCategoryKey?: string | null;
+  displayName: string;
+  shortTitle?: string | null;
+  subtitle?: string | null;
+  description?: string | null;
+  status: string;
+  seedItemIds?: Array<string | null> | null;
+  holdoutItemIds?: Array<string | null> | null;
+  rank?: number | null;
+  depth?: number | null;
+};
+
+export type NewsDeskAppendix = {
+  categorySetId: string;
+  corpusId: string;
+  displayName: string;
+  description?: string | null;
+  generatedAt?: string | null;
+  nodes: NewsDeskCategoryTreeNode[];
+};
+
+export type EditionContent = {
+  id: string;
+  source: ContentSource;
+  title: string;
+  editionDate: string;
+  items: PublicationItem[];
+  sections: EditionSection[];
+  layoutPlan: EditionLayoutPlan;
+  placeholderMode?: "emptyEdition";
+  suppressNewsDeskAppendix?: boolean;
+  newsDeskAppendix?: NewsDeskAppendix | null;
+  scenarioId?: string;
+  description?: string;
+  editionVideo?: ArticleVideoAsset | null;
+};
+
+export type EditionRouteSummary = {
+  id: string;
+  slug: string;
+  title: string;
+  editionDate: string;
+  publishedAt?: string | null;
+  description?: string | null;
+};
+
+export type ListPublishedEditionsOptions = {
+  limit?: number;
+  nextToken?: string | null;
+};
+
+export type PublishedEditionConnection = {
+  editions: EditionRouteSummary[];
+  nextToken?: string | null;
+};
+
+export type LoadEditionContentOptions = {
+  scenarioId?: string | null;
+  editionDate?: string | null;
+  editionSlug?: string | null;
+};
+
+export type GetEditionArticleOptions = {
+  editionDate: string;
+  articleSlug: string;
+};
+
+export type GetEditionItemOptions = {
+  editionDate: string;
+  itemSlug: string;
+};
+
+export type ContentRepository = {
+  loadEditionContent(options?: LoadEditionContentOptions): EditionContent | Promise<EditionContent>;
+  getLatestPublishedEdition(): EditionRouteSummary | null | Promise<EditionRouteSummary | null>;
+  getFirstPublishedEdition(): EditionRouteSummary | null | Promise<EditionRouteSummary | null>;
+  listPublishedEditions(options?: ListPublishedEditionsOptions): PublishedEditionConnection | Promise<PublishedEditionConnection>;
+  getArticle(slug: string): Article | undefined | Promise<Article | undefined>;
+  getEditionArticle(options: GetEditionArticleOptions): Article | undefined | Promise<Article | undefined>;
+  getEditionItem(options: GetEditionItemOptions): PublicationItem | undefined | Promise<PublicationItem | undefined>;
+  listArticleSlugs(): string[] | Promise<string[]>;
+};

package/lib/define-site.js

@@ -0,0 +1,3 @@
+export function defineSite(site) {
+    return site;
+}

package/lib/define-site.ts

@@ -0,0 +1,21 @@
+import type { PapyrusSiteBackendConfig } from "../amplify/site-backend-config";
+import type { SiteBrand } from "./site-brand";
+
+/**
+ * What a publication repo's `papyrus.config.ts` default-exports.
+ * Resolved by the `papyrus-site` alias (tsconfig `paths` in Papyrus itself,
+ * `withPapyrus()` in a publication repo). Also the argument of
+ * `defineSiteBackend(site)` so `ampx` never needs the brand graph.
+ */
+export type PapyrusSite = {
+  /** Brands this publication registers (in addition to Papyrus's built-ins). */
+  brands?: SiteBrand[];
+  /** Brand used when PAPYRUS_SITE_BRAND is unset. */
+  defaultBrand?: string;
+  /** Options for `defineSiteBackend(site)` (Amplify Gen 2 backend). */
+  backend?: PapyrusSiteBackendConfig;
+};
+
+export function defineSite(site: PapyrusSite): PapyrusSite {
+  return site;
+}

package/lib/demo-amplify-outputs.ts

@@ -0,0 +1,15 @@
+import { readAmplifyOutputsFile } from "./amplify-outputs-path";
+
+const DEMO_MARKERS = [
+  "demo-user-pool-client-id-not-a-secret",
+  "da2-demoapikeynotasecret000000",
+  "00000000-demo-4000-8000-000000000000",
+] as const;
+
+/** True when amplify_outputs.json is the offline demo stub (see amplify/fixtures/demo-amplify-outputs.json). */
+export function isDemoAmplifyOutputs(): boolean {
+  const outputs = readAmplifyOutputsFile();
+  if (!outputs) return false;
+  const serialized = JSON.stringify(outputs);
+  return DEMO_MARKERS.some((marker) => serialized.includes(marker));
+}

package/lib/dev-sandbox-editor-auth.ts

@@ -0,0 +1,18 @@
+export type DevSandboxEditorAuth = {
+  username: string;
+  password: string;
+};
+
+const DEFAULT_SEED_USERNAME = "papyrus-seed-editor@example.com";
+const DEFAULT_SEED_PASSWORD = "PapyrusSeed1!";
+
+export function resolveDevSandboxEditorAuth(): DevSandboxEditorAuth | null {
+  if (process.env.NODE_ENV !== "development") return null;
+  if (process.env.PAPYRUS_DEV_SEED_SIGNIN === "0") return null;
+
+  const username = process.env.PAPYRUS_SEED_USERNAME?.trim() || DEFAULT_SEED_USERNAME;
+  const password = process.env.PAPYRUS_SEED_PASSWORD?.trim() || DEFAULT_SEED_PASSWORD;
+  if (!username || !password) return null;
+
+  return { username, password };
+}