@devcabs/folio-engine 0.0.0-stage → 0.1.1

package/dist/types/canvas.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Folio Engine - Dynamic Canvas Type Definitions
+ * Location: src/types/canvas.ts
+ * Specification: docs/tasks/task8_1_data_models_and_default_factory.md
+ */
+export type CanvasElementType = 'section' | 'subsection' | 'text' | 'photo' | 'gallery' | 'chart';
+export interface CanvasElementBase {
+    id: string;
+    type: CanvasElementType;
+}
+export interface TextElement extends CanvasElementBase {
+    type: 'text';
+    pointId: string;
+    content: string;
+    as?: 'p' | 'blockquote';
+}
+export interface PhotoElement extends CanvasElementBase {
+    type: 'photo';
+    pointId: string;
+    src?: string;
+    /** Responsive image candidate string pre-baked for edge proxy delivery */
+    srcSet?: string;
+    /** Responsive sizes media query string */
+    sizes?: string;
+    /** Aspect ratio hint (e.g. "16/9", "4/3") */
+    aspectRatio?: string;
+    /** Original raw Drive URL preserved for fallback resilience */
+    rawDriveUrl?: string;
+    alt?: string;
+    caption?: string;
+    /** Optional Google Drive folder or item link */
+    driveUrl?: string;
+}
+export interface GalleryElement extends CanvasElementBase {
+    type: 'gallery';
+    pointId: string;
+    title?: string;
+    titlePointId?: string;
+    subtitle?: string;
+    subtitlePointId?: string;
+    driveUrl?: string;
+}
+export interface ChartElement extends CanvasElementBase {
+    type: 'chart';
+    chartId: string;
+    title: string;
+    subtitle?: string;
+}
+export type CanvasLeafElement = TextElement | PhotoElement | GalleryElement | ChartElement;
+export interface SubsectionElement extends CanvasElementBase {
+    type: 'subsection';
+    title: string;
+    titlePointId?: string;
+    subtitle?: string;
+    subtitlePointId?: string;
+    /** Leaf content items within this subsection */
+    elements: CanvasLeafElement[];
+}
+export type CanvasChildElement = SubsectionElement | CanvasLeafElement;
+export interface SectionElement extends CanvasElementBase {
+    type: 'section';
+    /** Two-digit sequential display number, e.g. "01", "02" */
+    number?: string;
+    /** Whether the section displays a sequential number badge */
+    isNumbered?: boolean;
+    title: string;
+    titlePointId?: string;
+    subtitle?: string;
+    subtitlePointId?: string;
+    /** Child elements and subsections contained within this section */
+    elements: CanvasChildElement[];
+}
+export type CanvasElement = SectionElement | CanvasChildElement;
+export interface NodeCanvasDocument {
+    nodeId: string;
+    version: number;
+    sections: SectionElement[];
+    updatedAt: string;
+}
+/**
+ * Type Guards for Canvas Elements
+ */
+export declare function isSectionElement(el: CanvasElement): el is SectionElement;
+export declare function isSubsectionElement(el: CanvasElement): el is SubsectionElement;
+export declare function isLeafElement(el: CanvasElement): el is CanvasLeafElement;
+export declare function isTextElement(el: CanvasElement): el is TextElement;
+export declare function isPhotoElement(el: CanvasElement): el is PhotoElement;
+export declare function isGalleryElement(el: CanvasElement): el is GalleryElement;
+export declare function isChartElement(el: CanvasElement): el is ChartElement;
+/**
+ * Unified Canvas Add & Edit Modal Contracts
+ * Aligned with docs/tasks/task9_8_unified_canvas_add_edit_modal_drawer.md
+ */
+export type CanvasModalMode = 'add' | 'edit';
+export type CanvasModalElementType = 'section' | 'subsection' | 'text' | 'photo' | 'gallery';
+export interface CanvasElementFormData {
+    /** For section, subsection, gallery, or text title */
+    title?: string;
+    /** For section numbering */
+    isNumbered?: boolean;
+    /** For narrative text content */
+    content?: string;
+    /** For text typography style */
+    as?: 'p' | 'blockquote';
+    /** For photo image source (data URL or external URL) */
+    src?: string;
+    /** For photo image accessibility description */
+    alt?: string;
+    /** For photo image caption */
+    caption?: string;
+    /** Whether photo caption is visible below image */
+    showCaption?: boolean;
+    /** For photo or gallery Google Drive folder URL */
+    driveUrl?: string;
+}

package/dist/types/chart.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Chart Contracts & TypeScript Data Models
+ * Document Reference: docs/tasks/task7_1_contracts_d3_math_sanitizer.md & docs/04_DATA_MODELS.md
+ *
+ * Strict contracts for the host application Data Charts.
+ * Supports Bar, Line, Donut, Scatter, and Histogram charts with number purity and zero URL leaks.
+ */
+import type { NodeCode } from './node';
+export type ChartType = 'bar' | 'line' | 'donut' | 'scatter' | 'histogram' | 'auto';
+export interface ChartSeries {
+    name: string;
+    data: (number | null)[];
+    color?: string;
+}
+export interface ScatterPoint {
+    x: number;
+    y: number;
+    label?: string;
+    group?: string;
+}
+export interface HistogramBin {
+    x0: number;
+    x1: number;
+    count: number;
+}
+/**
+ * Contextual visual configuration parameters editable via the Sidebar Drawer
+ */
+export interface ChartVisualConfig {
+    xMin?: number;
+    xMax?: number;
+    yMin?: number;
+    yMax?: number;
+    xLabel?: string;
+    yLabel?: string;
+    unit?: string;
+    tabName?: string;
+    sheetGid?: string;
+    range?: string;
+    excludeSummaryRows?: boolean;
+    transpose?: boolean;
+    binStrategy?: 'auto' | 'custom';
+    binCount?: number;
+    bucketSize?: number;
+    histogramYMode?: 'frequency' | 'relative';
+    showSummaryStats?: boolean;
+    showMedianMode?: boolean;
+    showReferenceGuide?: boolean;
+    barVariant?: 'standard' | 'progress';
+    targetValue?: number;
+    targetLabel?: string;
+    categoryColIndex?: number;
+    includedSeriesIndices?: number[];
+    sortBy?: 'none' | 'asc' | 'desc' | 'category-asc' | 'category-desc';
+    sortField?: string;
+    sortDirection?: 'asc' | 'desc';
+    orientation?: 'vertical' | 'horizontal';
+    barOrientation?: 'vertical' | 'horizontal';
+    stacked?: boolean;
+    showValues?: boolean;
+    autoScaleY?: boolean;
+    autoScaleX?: boolean;
+    startAtZero?: boolean;
+    startAtZeroX?: boolean;
+    curveInterpolation?: 'smooth' | 'straight' | 'none' | 'linear' | 'polynomial';
+    loessBandwidth?: number;
+    showAreaFill?: boolean;
+    markerSize?: 'compact' | 'regular' | 'prominent';
+    scatterXColIndex?: number;
+    scatterYColIndex?: number;
+    scatterLabelColIndex?: number;
+    scatterGroupColIndex?: number;
+    showCorrelationChip?: boolean;
+    donutVariant?: 'donut' | 'pie';
+    groupOthers?: boolean;
+    lastModifiedTime?: string;
+}
+export interface ChartDataset {
+    chartId: string;
+    title: string;
+    subtitle?: string;
+    unit?: string;
+    asOfDate: string;
+    chartType: ChartType;
+    nodeId?: NodeCode;
+    visualConfig?: ChartVisualConfig;
+    categories?: string[];
+    series?: ChartSeries[];
+    scatterPoints?: ScatterPoint[];
+    rawValues?: (number | null)[];
+    bins?: HistogramBin[];
+    sanitizedCsvContent: string;
+}
+export interface SheetChartConfig {
+    chartId: string;
+    sheetUrl: string;
+    tabName?: string;
+    sheetGid?: string;
+    range?: string;
+    defaultType?: ChartType;
+    titleOverride?: string;
+    subtitleOverride?: string;
+    unitOverride?: string;
+    nodeId: NodeCode;
+    visualConfig?: ChartVisualConfig;
+    cachedDataset?: (string | number | null)[][] | null;
+    updatedAt?: string;
+    updatedBy?: string;
+}
+export type ChartSyncStatus = 'idle' | 'syncing' | 'success' | 'pending_data' | 'error';
+export type ChartProblemCategory = 'unlinked' | 'connection_error' | 'data_format' | 'none';
+export interface ChartState {
+    dataset: ChartDataset | null;
+    status: ChartSyncStatus;
+    errorMessage?: string;
+    lastSyncedAt?: string;
+}

package/dist/types/developer.d.ts

@@ -0,0 +1,144 @@
+import React from 'react';
+import type { CloudDraftSyncStatus } from './draft';
+/**
+ * TypeScript Contracts for Developer Mode & Live Administrative Affordances
+ * Task 4.5.0: docs/tasks/task4_5_0_developer_mode.md
+ */
+export type PinVerificationState = 'idle' | 'verifying' | 'success' | 'error' | 'locked_out';
+export interface DeveloperSessionInfo {
+    unlockedAt: number | null;
+    expiresAt: number | null;
+    remainingMinutes: number;
+}
+export interface DevSessionLock {
+    id: 'active_session';
+    isLocked: boolean;
+    lockedBySessionId: string;
+    coordinatorLabel?: string;
+    lockedAt: string;
+    lastHeartbeatAt: string;
+    expiresAt: string;
+}
+export interface DevLockStatusResponse {
+    canAcquire: boolean;
+    currentLock?: DevSessionLock;
+    isSelfSession: boolean;
+}
+export interface DeveloperModeContextType {
+    /** Whether developer mode is currently active and authenticated */
+    isDevMode: boolean;
+    /** Whether the current client device meets PC/Desktop requirements (>=1024px, fine pointer) */
+    isDesktop: boolean;
+    /** Whether the PIN entry modal is currently displayed */
+    isPinModalOpen: boolean;
+    /** Verification lifecycle state */
+    pinState: PinVerificationState;
+    /** Number of remaining incorrect attempts before 1-minute lockout */
+    attemptsRemaining: number;
+    /** Lockout countdown remaining in seconds (0 when not locked out) */
+    lockoutRemainingSeconds: number;
+    /** Remaining session time in minutes */
+    sessionRemainingMinutes: number;
+    /** Whether the current PIN modal was triggered for session renewal */
+    isRenewal: boolean;
+    /** Open PIN modal (or renewal prompt) */
+    openPinModal: (isRenewal?: boolean, skipLockCheck?: boolean) => void;
+    /** Close PIN modal */
+    closePinModal: () => void;
+    /** Submit 4-digit PIN for cryptographic verification */
+    submitPin: (pin: string) => Promise<boolean>;
+    /** Exit developer mode immediately, clearing session unlock timestamp */
+    exitDevMode: (options?: {
+        discard?: boolean;
+    }) => void;
+    /** Whether the exit confirmation dialog is open */
+    isExitConfirmOpen: boolean;
+    /** Request exit from developer mode (prompts confirmation modal) */
+    requestExitDevMode: () => void;
+    /** Confirm exit from developer mode, closing dialog and exiting */
+    confirmExitDevMode: (options?: {
+        discard?: boolean;
+    }) => void;
+    /** Dismiss exit confirmation dialog without exiting */
+    closeExitConfirmModal: () => void;
+    /** Toggle developer mode: opens PIN modal if inactive, prompts exit if active */
+    toggleDevMode: () => void;
+    /** Unique session ID generated for this browser instance */
+    sessionId: string;
+    /** Whether Dev Mode entry is blocked because another coordinator holds the lock */
+    isLockBlocked: boolean;
+    /** Active lock metadata if blocked */
+    activeLockInfo: DevSessionLock | null;
+    /** Dismiss the blocked coordinator dialog */
+    closeLockBlockedModal: () => void;
+    /** Force release or refresh lock status */
+    refreshLockStatus: () => Promise<void>;
+    /** Whether there are unsaved draft changes in the active session */
+    hasUnpublishedChanges: boolean;
+    /** Update the dirty state of unpublished draft changes */
+    setHasUnpublishedChanges: (hasChanges: boolean) => void;
+    /** Whether the active version is currently hydrating from cloud storage */
+    isCloudHydrating?: boolean;
+    /** Current cloud DB-draft synchronization status */
+    cloudSyncStatus?: CloudDraftSyncStatus;
+    /** Display a floating Toast feedback capsule */
+    showToast: (message: string, type?: 'success' | 'error' | 'info') => void;
+}
+export type DevEditType = 'text' | 'link' | 'image' | 'file';
+export type DevAffordanceType = 'text' | 'link' | 'image' | 'file' | 'source' | 'indicator';
+export interface DevLinkData {
+    url: string;
+    label?: string;
+    openInNewTab?: boolean;
+}
+export interface DevImageData {
+    src: string;
+    alt: string;
+    caption?: string;
+    showCaption?: boolean;
+}
+export interface DevFileData {
+    name: string;
+    url: string;
+    reference?: string;
+    format?: 'pdf' | 'doc' | 'sheet' | 'other';
+    size?: string;
+}
+export interface DevActionAffordanceProps {
+    /** Identifier of the milestone or content node (e.g. 'stage-1', 'node-access') */
+    pointId?: string;
+    /** Type of affordance to render when developer mode is active */
+    type?: DevAffordanceType;
+    /** Optional custom action label (deprecated under Uniform Edit Standard) */
+    label?: string;
+    /** Callback when edit action is clicked */
+    onEditText?: () => void;
+    /** Callback when "Edit Source" action is clicked */
+    onEditSource?: () => void;
+    /** Optional link to associated Google Drive folder */
+    driveUrl?: string;
+    /** Current content for dynamic modal editing */
+    currentValue?: string | DevLinkData | DevImageData | DevFileData;
+    /** Default fallback content for dynamic modal editing */
+    defaultValue?: string | DevLinkData | DevImageData | DevFileData;
+    /** Direct update handler if bypassing useContent internal dispatch */
+    onSave?: (newValue: string) => void;
+    /** Direct reset handler if bypassing useContent internal dispatch */
+    onReset?: () => void;
+    /** Wrapped child component */
+    children: React.ReactNode;
+    /** Optional container class name */
+    className?: string;
+    /** Whether to render as an inline container instead of block */
+    inline?: boolean;
+    /** Whether the target content belongs to a section heading */
+    isSection?: boolean;
+    /** Whether the section is currently numbered */
+    isNumbered?: boolean;
+    /** Default numbering fallback */
+    defaultNumbered?: boolean;
+    /** Callback when section numbering is toggled */
+    onNumberedChange?: (isNumbered: boolean) => void;
+    /** Optional deterministic trigger identifier for canvas controls targeting */
+    editTriggerId?: string;
+}

package/dist/types/draft.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Folio Engine - Cloud DB-Draft Contracts
+ * Location: src/types/draft.ts
+ * Specification: docs/tasks/task11_2g_db_draft_and_blob_storage_pipeline.md
+ */
+import type { NodeCanvasDocument } from './canvas';
+export interface CloudDraftData {
+    id: string;
+    baseSnapshotId: string;
+    canvases: Record<string, NodeCanvasDocument>;
+    contentOverrides: Record<string, string>;
+    updatedAt: string;
+    updatedBySession?: string;
+    lockedBySession?: string;
+}
+export type CloudDraftSyncStatus = 'saved' | 'saving' | 'error' | 'offline';
+export interface DraftSyncStatusEventDetail {
+    status: CloudDraftSyncStatus;
+    lastSavedAt?: string;
+    error?: string;
+}

package/dist/types/edge.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Folio Engine — Cloudflare Pages Functions & Edge KV Schema Contracts
+ * Location: src/types/edge.ts
+ * Specification: docs/tasks/task15_1_edge_routing_and_kv_schema_architecture.md
+ */
+import { z } from 'zod';
+import type { NodeCanvasDocument } from './canvas';
+import type { ChartDataset } from './chart';
+import type { SyncedSourceItem } from './source';
+import type { NodeCode } from './node';
+export declare const VALID_NODES: readonly NodeCode[];
+export type ValidNodeId = typeof VALID_NODES[number];
+/**
+ * Cloudflare KV Namespace Interface for Edge Bindings
+ */
+export interface KVNamespace {
+    get(key: string, options?: {
+        type?: 'text' | 'json' | 'arrayBuffer' | 'stream';
+        cacheTtl?: number;
+    }): Promise<string | null>;
+    get<T>(key: string, type: 'json'): Promise<T | null>;
+    put(key: string, value: string | ArrayBuffer | ReadableStream, options?: {
+        expiration?: number;
+        expirationTtl?: number;
+        metadata?: unknown;
+    }): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        keys: {
+            name: string;
+            expiration?: number;
+            metadata?: unknown;
+        }[];
+        list_complete: boolean;
+        cursor?: string;
+    }>;
+}
+/**
+ * Cloudflare Pages Functions Environment Bindings
+ */
+export interface EdgeEnv {
+    KV_ENGINE_PUBLIC: KVNamespace;
+    VITE_SUPABASE_URL?: string;
+    VITE_SUPABASE_ANON_KEY?: string;
+    [key: string]: unknown;
+}
+/**
+ * Cloudflare Pages Functions EventContext Contract
+ */
+export interface PagesFunctionEventContext<Env = EdgeEnv, P extends string = string, Data = unknown> {
+    request: Request;
+    functionPath: string;
+    waitUntil: (promise: Promise<unknown>) => void;
+    next: (input?: Request | string, init?: RequestInit) => Promise<Response>;
+    env: Env;
+    params: Record<P, string | string[]>;
+    data: Data;
+}
+/**
+ * Cached Indicator Dataset (serialized tabular/D3 data stored in KV)
+ */
+export type CachedIndicatorDataset = ChartDataset;
+/**
+ * Synced Evidence Metadata
+ */
+export interface SyncedSourceMetadata {
+    pointId: string;
+    folderUrl?: string;
+    folderTitle?: string;
+    description?: string;
+    lastSyncedAt?: string;
+    items?: SyncedSourceItem[];
+}
+/**
+ * Route Contract 1: GET /api/public/node/:nodeId
+ */
+export interface PublicNodePayload {
+    nodeId: string;
+    snapshotId: string;
+    version: number;
+    updatedAt: string;
+    canvas: NodeCanvasDocument;
+    chartDatasets: Record<string, CachedIndicatorDataset>;
+    sourceMetadata: Record<string, SyncedSourceMetadata>;
+}
+/**
+ * Route Contract 2: GET /api/public/manifest
+ */
+export interface PublicPortalManifestPayload {
+    activeSnapshotId: string;
+    publishedAt: string;
+    nodeIds: string[];
+    schemaVersion: number;
+}
+export declare const PublicPortalManifestPayloadSchema: z.ZodObject<{
+    activeSnapshotId: z.ZodString;
+    publishedAt: z.ZodString;
+    nodeIds: z.ZodArray<z.ZodString, "many">;
+    schemaVersion: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    activeSnapshotId: string;
+    publishedAt: string;
+    nodeIds: string[];
+    schemaVersion: number;
+}, {
+    activeSnapshotId: string;
+    publishedAt: string;
+    nodeIds: string[];
+    schemaVersion: number;
+}>;
+export declare const NodeCanvasDocumentSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    version: z.ZodNumber;
+    sections: z.ZodArray<z.ZodAny, "many">;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    nodeId: string;
+    version: number;
+    sections: any[];
+    updatedAt: string;
+}, {
+    nodeId: string;
+    version: number;
+    sections: any[];
+    updatedAt: string;
+}>;
+export declare const CachedIndicatorDatasetSchema: z.ZodObject<{
+    chartId: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodOptional<z.ZodString>;
+    unit: z.ZodOptional<z.ZodString>;
+    asOfDate: z.ZodString;
+    chartType: z.ZodString;
+    sanitizedCsvContent: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    chartId: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodOptional<z.ZodString>;
+    unit: z.ZodOptional<z.ZodString>;
+    asOfDate: z.ZodString;
+    chartType: z.ZodString;
+    sanitizedCsvContent: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    chartId: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodOptional<z.ZodString>;
+    unit: z.ZodOptional<z.ZodString>;
+    asOfDate: z.ZodString;
+    chartType: z.ZodString;
+    sanitizedCsvContent: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export declare const SyncedSourceMetadataSchema: z.ZodObject<{
+    pointId: z.ZodString;
+    folderUrl: z.ZodOptional<z.ZodString>;
+    folderTitle: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    lastSyncedAt: z.ZodOptional<z.ZodString>;
+    items: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    pointId: z.ZodString;
+    folderUrl: z.ZodOptional<z.ZodString>;
+    folderTitle: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    lastSyncedAt: z.ZodOptional<z.ZodString>;
+    items: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    pointId: z.ZodString;
+    folderUrl: z.ZodOptional<z.ZodString>;
+    folderTitle: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    lastSyncedAt: z.ZodOptional<z.ZodString>;
+    items: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+}, z.ZodTypeAny, "passthrough">>;
+export declare const PublicNodePayloadSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    snapshotId: z.ZodString;
+    version: z.ZodNumber;
+    updatedAt: z.ZodString;
+    canvas: z.ZodObject<{
+        nodeId: z.ZodString;
+        version: z.ZodNumber;
+        sections: z.ZodArray<z.ZodAny, "many">;
+        updatedAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        nodeId: string;
+        version: number;
+        sections: any[];
+        updatedAt: string;
+    }, {
+        nodeId: string;
+        version: number;
+        sections: any[];
+        updatedAt: string;
+    }>;
+    chartDatasets: z.ZodRecord<z.ZodString, z.ZodAny>;
+    sourceMetadata: z.ZodRecord<z.ZodString, z.ZodAny>;
+}, "strip", z.ZodTypeAny, {
+    nodeId: string;
+    version: number;
+    updatedAt: string;
+    snapshotId: string;
+    canvas: {
+        nodeId: string;
+        version: number;
+        sections: any[];
+        updatedAt: string;
+    };
+    chartDatasets: Record<string, any>;
+    sourceMetadata: Record<string, any>;
+}, {
+    nodeId: string;
+    version: number;
+    updatedAt: string;
+    snapshotId: string;
+    canvas: {
+        nodeId: string;
+        version: number;
+        sections: any[];
+        updatedAt: string;
+    };
+    chartDatasets: Record<string, any>;
+    sourceMetadata: Record<string, any>;
+}>;
+/**
+ * Computes a deterministic weak ETag for HTTP cache negotiation (304 Not Modified).
+ * Fast, synchronous, zero-dependency, works identically in Workers, Node, and browser.
+ */
+export declare function computeWeakEtag(content: string): string;