@bitflow/core 0.5.4 → 0.7.0

package/dist/attempt.d.ts

@@ -0,0 +1,67 @@
+import { type Result } from "./errors";
+import { type AttemptSnapshot, type BitflowDocument, type Confidence } from "./schema";
+export declare const createAttempt: (doc: BitflowDocument, options?: {
+    attemptId?: string;
+    now?: Date;
+    /** Injectable only so tests can draw pools deterministically. */
+    random?: () => number;
+}) => Result<AttemptSnapshot>;
+/**
+ * Validates a snapshot from the host against the document it claims to belong
+ * to. Callers must treat a failure as "keep the current attempt untouched" —
+ * a half-restored attempt would silently lose a learner's work.
+ */
+export declare const restoreAttempt: (doc: BitflowDocument, input: unknown) => Result<AttemptSnapshot>;
+export declare const abandonAttempt: (snapshot: AttemptSnapshot, now?: Date) => AttemptSnapshot;
+/** A durable answer change, without evaluating it. */
+export declare const setAnswer: (snapshot: AttemptSnapshot, nodeId: string, answer: unknown, now?: Date) => AttemptSnapshot;
+export declare const setConfidence: (snapshot: AttemptSnapshot, nodeId: string, confidence: Confidence, now?: Date) => AttemptSnapshot;
+export declare const setReasoning: (snapshot: AttemptSnapshot, nodeId: string, reasoning: string, now?: Date) => AttemptSnapshot;
+/**
+ * Runs the bit's evaluator and stores answer, result and try count together, so
+ * a snapshot never shows a result that belongs to a different answer.
+ */
+/**
+ * An attempt already sitting at `nodeId`.
+ *
+ * For previewing one step of a long flow: reaching the last task of a
+ * twenty-step assessment by answering the nineteen in front of it is not a
+ * reasonable thing to ask of someone editing the twentieth. The history holds
+ * only this node, so there is nothing behind it to go back to — a preview
+ * starting in the middle should not pretend the middle was reached.
+ */
+export declare const attemptAt: (doc: BitflowDocument, nodeId: string, options?: {
+    attemptId?: string;
+    now?: Date;
+    random?: () => number;
+}) => Result<AttemptSnapshot>;
+export declare const evaluateNode: (doc: BitflowDocument, snapshot: AttemptSnapshot, nodeId: string, answer?: unknown, now?: Date) => Promise<Result<AttemptSnapshot>>;
+/**
+ * Records that the learner passed on a node. The try counts (so branching on
+ * `tries` sees it) but no result is stored, which keeps it out of the score.
+ */
+export declare const skipNode: (snapshot: AttemptSnapshot, nodeId: string, now?: Date) => AttemptSnapshot;
+/**
+ * Clears the result so the learner can answer again. The try count is kept —
+ * it is the record of how many attempts it took.
+ */
+export declare const retryNode: (snapshot: AttemptSnapshot, nodeId: string, now?: Date) => AttemptSnapshot;
+export declare const goNext: (doc: BitflowDocument, snapshot: AttemptSnapshot, now?: Date) => AttemptSnapshot;
+/**
+ * Steps back through the visited history. The step is popped so going forward
+ * again re-evaluates the branch — an answer changed in between must be able to
+ * send the learner down a different path.
+ */
+export declare const goPrevious: (doc: BitflowDocument, snapshot: AttemptSnapshot, now?: Date) => AttemptSnapshot;
+export declare const canGoPrevious: (doc: BitflowDocument, snapshot: AttemptSnapshot) => boolean;
+/**
+ * Jumps straight to a step the learner has already been to.
+ *
+ * Only offered when the flow allows free movement, and only backwards: the
+ * history is truncated to the step jumped to, exactly as stepping back does, so
+ * going forward again re-runs every branch in between. Answers and results stay
+ * put — the jump is a change of view, not an undo.
+ */
+export declare const goTo: (doc: BitflowDocument, snapshot: AttemptSnapshot, nodeId: string, now?: Date) => AttemptSnapshot;
+export declare const isComplete: (snapshot: AttemptSnapshot) => boolean;
+export declare const isAtEnd: (doc: BitflowDocument, snapshot: AttemptSnapshot) => boolean;

package/dist/condition.d.ts

@@ -0,0 +1,38 @@
+import type { BitResult, Condition, ValueRef } from "./schema";
+/**
+ * Everything a branch may read out of the running attempt.
+ *
+ * Built by `conditionContext(doc, snapshot)`; nothing here is derived at
+ * comparison time, so replaying the same context always picks the same path.
+ */
+export type ConditionContext = {
+    answers: Record<string, unknown>;
+    results: Record<string, BitResult>;
+    tries: Record<string, number>;
+    /** How many times each node has been shown, counted off the history. */
+    visits: Record<string, number>;
+    /** `0`–`1` per node, for the steps the learner was asked about. */
+    confidence: Record<string, number>;
+    /** Seconds spent per node, including the stretch in progress. */
+    timeSpent: Record<string, number>;
+    /** Seconds spent across the whole attempt. */
+    totalTimeSpent: number;
+    /** Seconds left on the flow's own limit, or `null` when it has none. */
+    timeRemaining: number | null;
+    /** Node ids oldest first, which is what a `last` scope counts back through. */
+    history: string[];
+    /** Node id → section id, for a section-scoped count or score. */
+    sections: Record<string, string>;
+};
+/**
+ * Reads `a.b.0.c` out of a nested value. Returns `undefined` for any missing
+ * segment rather than throwing, so a condition that points at a node the
+ * learner has not reached yet is simply false instead of fatal.
+ */
+export declare const getPath: (value: unknown, path?: string) => unknown;
+export declare const resolveValueRef: (ref: ValueRef, context: ConditionContext) => unknown;
+export declare const evaluateCondition: (condition: Condition, context: ConditionContext) => boolean;
+/** Every node id a condition reads, for validation and dependency checks. */
+export declare const conditionNodeIds: (condition: Condition) => string[];
+/** Every section id a condition reads, so validation can catch a stale one. */
+export declare const conditionSectionIds: (condition: Condition) => string[];

package/dist/engine.d.ts

@@ -0,0 +1,190 @@
+import { type ConditionContext } from "./condition";
+import type { AttemptSnapshot, BitEdge, BitflowDocument, BitflowMeta, BitNode, BitResult } from "./schema";
+export declare const getNode: (doc: BitflowDocument, nodeId: string) => BitNode | undefined;
+export declare const outgoingEdges: (doc: BitflowDocument, nodeId: string) => BitEdge[];
+export declare const incomingEdges: (doc: BitflowDocument, nodeId: string) => BitEdge[];
+/**
+ * Where a fresh attempt begins: the first registered `start` bit, else the
+ * first node nothing points at, else simply the first node. The fallbacks
+ * matter because tooling (the VS Code source view, validation) inspects
+ * documents without every bit package loaded.
+ */
+export declare const startNodeId: (doc: BitflowDocument) => string | undefined;
+/**
+ * The nodes belonging to a pool, in document order.
+ *
+ * Membership is read off the nodes rather than held as a list on the pool, so
+ * a deleted step leaves nothing dangling behind it.
+ */
+export declare const poolMembers: (doc: BitflowDocument, poolId: string) => BitNode[];
+/**
+ * Chooses `draw` members of each pool.
+ *
+ * `random` is injectable so a test can be deterministic; nothing else passes
+ * it. A pool asking for more members than it has simply gets all of them —
+ * validation warns the author, and a learner mid-assessment is the wrong place
+ * to enforce it.
+ */
+export declare const drawPools: (doc: BitflowDocument, random?: () => number) => Record<string, string[]>;
+/**
+ * Whether this attempt walks through `nodeId` at all.
+ *
+ * Everything outside a pool is always active. A pool member is active only if
+ * this attempt drew it — and if the attempt has no draw recorded for its pool
+ * (an older snapshot, or a pool added since) it stays active, because hiding
+ * steps from a learner on the strength of missing data is the worse failure.
+ */
+export declare const isActiveNode: (snapshot: AttemptSnapshot, node: BitNode | undefined) => boolean;
+export declare const isTerminalNode: (doc: BitflowDocument, nodeId: string) => boolean;
+/**
+ * Edges that leave a pool — source inside it, target outside.
+ *
+ * A shuffled pool navigates by its drawn order rather than by its internal
+ * wiring, so once the order runs out the only edges that still mean anything
+ * are the ones pointing out of it. Which member happens to carry them does not
+ * matter, and must not: after a shuffle the last member is a different one for
+ * every learner.
+ *
+ * There is no matching `poolEntryEdges`, because the way *in* needs no rule:
+ * every edge into a shuffled pool lands on whichever member the draw put first
+ * (`redirectIntoPool`), so any number of them behave the same. Only the way out
+ * is ambiguous, and `validateFlow` is where that gets said.
+ */
+export declare const poolExitEdges: (doc: BitflowDocument, poolId: string) => BitEdge[];
+/**
+ * Where the learner goes next, and over which edge.
+ *
+ * The edge is part of the answer because `resetTarget` lives on it: the runtime
+ * has to know how it arrived somewhere to know what to clear on getting there.
+ */
+export type NextStep = {
+    nodeId: string;
+    /** Absent when the step came from a pool's drawn order rather than an edge. */
+    edge?: BitEdge;
+};
+export type NextStepOptions = {
+    /**
+     * Pool members this attempt did not draw. They are stepped over as though
+     * the graph did not contain them, which is what lets a pool be twenty
+     * ordinary nodes chained together rather than a construct of its own.
+     */
+    isActive?: (node: BitNode) => boolean;
+    /**
+     * Pool id → the members this attempt drew, in the order to show them. Only
+     * consulted for a pool with `shuffle` on; `AttemptSnapshot.pools` is what
+     * goes here.
+     */
+    order?: Record<string, string[]>;
+};
+/**
+ * The step that follows `currentId`, or `null` when the run is over.
+ *
+ * Pure: branching reads only the attempt context and the draw the attempt
+ * already recorded, so replaying the same inputs always picks the same path.
+ */
+export declare const nextStep: (doc: BitflowDocument, currentId: string, context: ConditionContext, options?: NextStepOptions) => NextStep | null;
+/** `nextStep`, for callers that only need to know where. */
+export declare const nextNodeId: (doc: BitflowDocument, currentId: string, context: ConditionContext, isActive?: (node: BitNode) => boolean, order?: Record<string, string[]>) => string | null;
+/**
+ * The previous node, read off the attempt's own history rather than walked
+ * backwards through the graph. With conditions on edges a reverse walk cannot
+ * tell which branch was actually taken.
+ */
+export declare const previousNodeId: (snapshot: AttemptSnapshot) => string | null;
+/** One row of the step list free navigation shows. */
+export type VisitedStep = {
+    nodeId: string;
+    node: BitNode;
+    /** Where it sits in the list, 1-based. */
+    position: number;
+    current: boolean;
+    /** A task the learner has a result for. Always false for a content step. */
+    answered: boolean;
+    /** A task with no result yet — the thing a check-your-work list is for. */
+    outstanding: boolean;
+    section?: BitflowMeta["sections"][number];
+};
+/**
+ * The steps the learner has been to, oldest first and each one once.
+ *
+ * Read off the history rather than the graph: with conditions on edges the
+ * document cannot say which steps a particular learner saw. A step visited
+ * twice — a remediation loop — is one row, at the position it first appeared.
+ */
+export declare const visitedSteps: (doc: BitflowDocument, snapshot: AttemptSnapshot) => VisitedStep[];
+/**
+ * Whether the learner may jump straight to `nodeId`.
+ *
+ * Only somewhere they have already been, and only when the flow allows free
+ * movement. Jumping forward is not on offer at any setting: which step comes
+ * next depends on answers that have not been given yet, so there is nothing
+ * truthful to jump to.
+ */
+export declare const canGoTo: (doc: BitflowDocument, snapshot: AttemptSnapshot, nodeId: string) => boolean;
+/** The section a step belongs to, if the flow still declares one. */
+export declare const sectionOf: (doc: BitflowDocument, node: BitNode | undefined) => BitflowMeta["sections"][number] | undefined;
+/** The nodes in a section, in document order. */
+export declare const sectionMembers: (doc: BitflowDocument, sectionId: string) => BitNode[];
+/**
+ * Whether the learner may pass on this task.
+ *
+ * The task decides when it says so, otherwise the flow does. Read off the data
+ * rather than through the bit, so a bit never has to know the setting exists —
+ * the same bargain `weight` and `timeLimit` already make.
+ */
+export declare const canSkip: (doc: BitflowDocument, node: BitNode | undefined) => boolean;
+/**
+ * Whether the learner may leave this step yet.
+ *
+ * Only a bit that declares `isComplete` can hold them, and only that bit knows
+ * why — the runtime disables Next and leaves the explanation to the step. A
+ * bit whose data does not parse is not held: refusing to let someone past a
+ * step that is broken anyway traps them in the assessment.
+ */
+export declare const canLeaveNode: (node: BitNode | undefined, answer: unknown) => boolean;
+export declare const computeScore: (snapshot: AttemptSnapshot) => {
+    earned: number;
+    possible: number;
+};
+/**
+ * Everything a branch may read, gathered out of the attempt in one place.
+ *
+ * Takes the document as well as the snapshot because time limits, sections and
+ * the flow's own clock are properties of the assessment, not of the run.
+ */
+export declare const conditionContext: (doc: BitflowDocument, snapshot: AttemptSnapshot, now?: Date) => ConditionContext;
+export declare const collectAnswers: (snapshot: AttemptSnapshot, nodeIds?: string[]) => Record<string, unknown>;
+export declare const collectResults: (snapshot: AttemptSnapshot, nodeIds?: string[]) => Record<string, BitResult>;
+/**
+ * Hops from `fromId` to the nearest (`optimistic`) or furthest (`pessimistic`)
+ * terminal node, ignoring conditions — this feeds the progress indicator, which
+ * must not depend on answers the learner has not given yet. Cycles are cut, and
+ * a node with no route to an end returns `Infinity`.
+ */
+export declare const distanceToEnd: (doc: BitflowDocument, fromId: string, mode?: "pessimistic" | "optimistic", 
+/**
+ * Undrawn pool members cost nothing to pass, so a progress bar counts the
+ * five steps this learner will take rather than the twenty in the file.
+ */
+isActive?: (node: BitNode) => boolean) => number;
+/**
+ * Milliseconds spent on one task, including the stretch in progress.
+ *
+ * Time *spent*, not elapsed wall clock: `elapsedMs` only accumulates while the
+ * learner is actually on a node, so closing the tab pauses the clock. That is
+ * the only rule a snapshot can honour across a reload, and the fairer one.
+ */
+export declare const timeSpentOn: (snapshot: AttemptSnapshot, nodeId: string, now?: Date) => number;
+/** Milliseconds spent across the whole attempt, on the same basis. */
+export declare const timeSpent: (snapshot: AttemptSnapshot, now?: Date) => number;
+/** The task's own limit in milliseconds, or `null` when it has none. */
+export declare const taskTimeLimit: (node: BitNode | undefined) => number | null;
+export type FlowProgress = {
+    /** Nodes the learner has already been shown, including the current one. */
+    visited: number;
+    /** Best-case hops still to go; `Infinity` when the graph has no route out. */
+    remaining: number;
+    /** `0`–`1`, or `1` once the attempt is finished. */
+    ratio: number;
+};
+export declare const flowProgress: (doc: BitflowDocument, snapshot: AttemptSnapshot) => FlowProgress;

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+import type { $ZodIssue } from "zod/v4/core";
+export declare const BITFLOW_ERROR_CODES: readonly ["INVALID_FLOW", "INVALID_ATTEMPT", "FLOW_ATTEMPT_MISMATCH", "UNKNOWN_BIT_TYPE", "LOAD_FAILED", "EVALUATION_FAILED"];
+export type BitflowErrorCode = (typeof BITFLOW_ERROR_CODES)[number];
+export type Diagnostic = {
+    /** Dot/bracket path into the offending document, e.g. `nodes.2.data.title`. */
+    path: string;
+    message: string;
+};
+/**
+ * The payload of every `bitflow-error` event. A plain object rather than an
+ * `Error` subclass so it survives `structuredClone` and `JSON.stringify` on
+ * the way to a host that wants to log or display it.
+ */
+export type BitflowError = {
+    code: BitflowErrorCode;
+    message: string;
+    diagnostics?: Diagnostic[];
+};
+export declare const bitflowError: (code: BitflowErrorCode, message: string, diagnostics?: Diagnostic[]) => BitflowError;
+/** Turns zod issues into the flat `{ path, message }` shape hosts receive. */
+export declare const toDiagnostics: (issues: readonly $ZodIssue[]) => Diagnostic[];
+export type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: BitflowError;
+};

package/dist/i18n.d.ts

@@ -0,0 +1,35 @@
+import { type Locale } from "./schema";
+export declare const DEFAULT_LOCALE: Locale;
+/** Flat key → message. One JSON file per locale, per package. */
+export type Catalog = Record<string, string>;
+export type Catalogs = Partial<Record<Locale, Catalog>> & {
+    en: Catalog;
+};
+export declare const isLocale: (value: unknown) => value is Locale;
+/**
+ * Picks the closest supported locale. Accepts full BCP-47 tags, so `"de-AT"`
+ * and `navigator.language` work without the caller trimming them first.
+ */
+export declare const resolveLocale: (requested?: string | null, fallback?: Locale) => Locale;
+/**
+ * Substitutes `{name}` placeholders. Missing variables are left as-is rather
+ * than blanked, because a visible `{count}` in the UI is a far louder bug
+ * report than an empty gap.
+ */
+export declare const interpolate: (message: string, vars?: Record<string, string | number>) => string;
+/**
+ * Looks a key up in `locale`, falling back to English and finally to the key
+ * itself — an untranslated string still renders something the reader can act
+ * on, which is what the old `@vocab` build step guaranteed at compile time.
+ */
+export declare const translate: (catalogs: Catalogs, key: string, locale: string | Locale | undefined, vars?: Record<string, string | number>) => string;
+export type Translator = (key: string, vars?: Record<string, string | number>) => string;
+/** Binds catalogs and a locale once, for components that translate a lot. */
+export declare const createTranslator: (catalogs: Catalogs, locale?: string | Locale) => Translator;
+export declare const formatDate: (value: Date | string | number, locale?: string | Locale, options?: Intl.DateTimeFormatOptions) => string;
+export declare const formatDateTime: (value: Date | string | number, locale?: string | Locale) => string;
+/**
+ * A duration as `1:04` or `2:01:04`. Learner-facing timings are minutes, not
+ * calendar units, so `Intl.DurationFormat` would be both heavier and wordier.
+ */
+export declare const formatDuration: (ms: number) => string;

package/dist/id.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Ids only have to be unique inside one document or one attempt, so a UUID is
+ * plenty and needs no coordination. `crypto.randomUUID` is unavailable on
+ * insecure origins and in a few older embedders, hence the fallback.
+ */
+export declare const createId: (prefix?: string) => string;

package/dist/image.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+/**
+ * A picture, carried inside the document rather than linked from it.
+ *
+ * `.bitflow` files are moved around — mailed between teachers, dropped into a
+ * VLE, opened from a memory stick, taken offline — and a linked image breaks
+ * on every one of those journeys, usually in front of a class. Embedding costs
+ * file size, which the authoring form spends deliberately by scaling and
+ * re-encoding what it is given.
+ */
+export declare const ImageSchema: z.ZodObject<{
+    src: z.ZodDefault<z.ZodString>;
+    alt: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type Image = z.infer<typeof ImageSchema>;
+/** Whether a source is embedded in the document rather than fetched. */
+export declare const isEmbedded: (src: string) => boolean;
+/**
+ * Roughly how many bytes a `data:` URI costs in the saved file.
+ *
+ * The base64 payload is 4 characters per 3 bytes, and the JSON that carries it
+ * stores those characters one byte each — so the string length *is* the cost,
+ * which is the number an author needs when deciding whether a picture is worth
+ * it. Anything that is not a data URI costs only its own length.
+ */
+export declare const sourceBytes: (src: string) => number;
+/** `1.4 MB`, for telling an author what a picture is costing them. */
+export declare const formatBytes: (bytes: number) => string;
+/**
+ * The size a picture is scaled to: never enlarged, never longer than
+ * `maxEdge` on its longest side.
+ *
+ * A phone photograph is 4000px across and a drag-and-drop background is shown
+ * at perhaps 800. Storing the original would put megabytes into every copy of
+ * the file to no visible effect.
+ */
+export declare const scaledSize: (width: number, height: number, maxEdge: number) => {
+    width: number;
+    height: number;
+};

package/dist/index.d.ts

@@ -1,11 +1,13 @@
-export * from "./bits";
-export * from "./bitsSchema";
-export * from "./do";
-export * from "./doSchema";
-export * from "./findLast";
-export * from "./flow";
-export * from "./flowSchema";
-export * from "./groupBy";
-export * from "./lerpColor";
-export * from "./levenshtein";
-export * from "./uuid";
+export * from "./attempt";
+export * from "./image";
+export * from "./condition";
+export * from "./engine";
+export * from "./errors";
+export * from "./i18n";
+export * from "./id";
+export * from "./registry";
+export * from "./score";
+export * from "./schema";
+export * from "./validate";
+export * from "./styles";
+export * from "./validateCondition";