@divlet/core 0.0.2 → 0.0.3

package/dist/core/lib/project.js

@@ -7,9 +7,9 @@
  * instance of it, with `descendants` overrides addressed by component node IDs (joined by
  * "/" to reach into nested instances), following the Pencil .pen conventions.
  */
-import path from 'node:path';
 import { readAssets, validateAssetPatch } from "./assets.js";
 import { DivletError, validateDocument, SOURCE_LIMITS, LIMITS, PROJECTION_LIMITS, documentLimits, validateTokens, validateCss, validateMetadata, string, merge, REF, } from "./model.js";
+import { withinUtf8Budget } from "./validation.js";
 export const PROJECT_SCHEMA = 1;
 const MAX_FRAMES = SOURCE_LIMITS.roots;
 const PROJECT_KEYS = new Set(['schemaVersion', 'name', 'version', 'tokens', 'css', 'metadata', 'outputDir', 'assets', 'frames']);
@@ -43,7 +43,7 @@ export function validateSettings(source = {}) {
     if (!Number.isSafeInteger(version) || version < 1)
         fail('INVALID_PROJECT', 'Project version must be a positive integer');
     const outputDir = input.outputDir ?? null;
-    if (outputDir !== null && (typeof outputDir !== 'string' || !outputDir.trim() || outputDir.length > 2048 || /[\\\u0000-\u001f]/.test(outputDir) || path.posix.isAbsolute(outputDir) || path.win32.isAbsolute(outputDir) || /^[a-z]:/i.test(outputDir)))
+    if (outputDir !== null && (typeof outputDir !== 'string' || !outputDir.trim() || outputDir.length > 2048 || /[\\\u0000-\u001f]/.test(outputDir) || outputDir.startsWith('/') || /^[a-z]:/i.test(outputDir)))
         fail('INVALID_OUTPUT_DIR', 'outputDir must be a relative directory path, or null for the default.');
     return {
         name,
@@ -115,7 +115,7 @@ export function writeProject(settings, frames) {
         fail('INVALID_PROJECT', `A project can hold at most ${MAX_FRAMES} frames`);
     const assets = readAssets(settings.assets ?? {}).tree;
     const text = JSON.stringify({ schemaVersion: PROJECT_SCHEMA, name: settings.name, version: settings.version, tokens: settings.tokens, css: settings.css, metadata: settings.metadata, ...(settings.outputDir !== null && settings.outputDir !== undefined ? { outputDir: settings.outputDir } : {}), ...(Object.keys(assets).length ? { assets } : {}), frames: frames.map(storedFrame) }, null, 2) + '\n';
-    if (Buffer.byteLength(text) > SOURCE_LIMITS.bytes)
+    if (!withinUtf8Budget(text, SOURCE_LIMITS.bytes))
         fail('FILE_TOO_LARGE', 'The serialized project exceeds the source read limit.');
     return text;
 }

package/dist/core/lib/render.d.ts

@@ -1,14 +1,7 @@
 import type { DocumentModel, Limits, NodeId } from './model.ts';
 import type { FrameLookup, ProjectSettings } from './project.ts';
-/** What preparing a frame produces: the validated document, the preview page, the generated file, its dependencies and the
- *  classes that do nothing. Nothing here is state: a caller decides what to publish. */
-export interface PreparedFrame {
-    document: DocumentModel;
-    html: string;
-    fileHtml: string;
-    uses: string[];
-    unknown: Record<string, string[]>;
-}
+import type { PreparedFrame } from './prepare.ts';
+export type { PreparedFrame, FrameCompiler } from './prepare.ts';
 export interface PrepareOptions {
     lookup?: FrameLookup;
     settings?: ProjectSettings | null;

package/dist/core/lib/render.js

@@ -2,44 +2,19 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
-import { isDeepStrictEqual } from 'node:util';
-import postcss from 'postcss';
-import { validateDocument, DivletError, LIMITS, documentLimits } from "./model.js";
-import { expandFrame, instancesOf, storedFrame } from "./project.js";
-import { encodeHtml, decodeHtml, renderFile } from "./codec.js";
+import { LIMITS } from "./model.js";
+import { storedFrame } from "./project.js";
 import { compileClasses, unknownClasses } from "./engine.js";
+import { prepareFrameWith } from "./prepare.js";
 const PACKAGE_ROOT = fileURLToPath(new URL('../../', import.meta.url));
-const MAX_FILE_BYTES = 4 * 1024 * 1024;
 const digest = (value) => createHash('sha256').update(value).digest('hex');
-const sameDocument = (a, b) => isDeepStrictEqual({ ...a, version: 0 }, { ...b, version: 0 });
-function fail(code, message) { throw new DivletError(code, message); }
-function checkAtRules(css) {
-    const tree = postcss.parse(css || '');
-    const allowed = new Set(['media', 'supports', 'layer', 'keyframes', '-webkit-keyframes', 'font-face', 'container', 'property', 'starting-style', 'scope']);
-    tree.walkAtRules(rule => {
-        if (!allowed.has(rule.name.toLowerCase()))
-            fail('UNSUPPORTED_CSS', `CSS @${rule.name} is not allowed in a divlet project. Build directives and imports are disabled.`);
-    });
-    if (/<\/style/i.test(css))
-        fail('UNSUPPORTED_CSS', 'A style element closing sequence is not allowed in authored CSS.');
-}
-export async function prepareFrame(input, { lookup = () => undefined, settings = null, limits = LIMITS } = {}) {
-    documentLimits(limits);
-    const document = validateDocument(input, { limits });
-    const expanded = expandFrame(document, lookup, settings, { limits });
-    checkAtRules(expanded.document.css);
-    const candidates = [...new Set(Object.values(expanded.document.nodes).flatMap(node => (node.type === 'element' ? node.className : '').split(/\s+/)).filter(Boolean))];
-    const compiledCss = await compileClasses(expanded.document.tokens, candidates, PACKAGE_ROOT);
-    const instances = new Map(instancesOf(document).map(item => [item.id, `${item.frame}/${item.node}`]));
-    const html = encodeHtml(expanded.document, { compiledCss, parts: expanded.parts, instances, limits });
-    if (Buffer.byteLength(html) > MAX_FILE_BYTES)
-        fail('FILE_TOO_LARGE', 'The rendered frame exceeds the 4 MiB limit.');
-    const decoded = decodeHtml(html, { previous: expanded.document, limits });
-    if (!sameDocument(expanded.document, decoded))
-        fail('UNREPRESENTABLE_HTML', 'The frame does not survive HTML parsing unchanged (check element nesting); the last valid preview was retained.');
-    const own = Object.fromEntries(Object.values(document.nodes).flatMap(node => (node.type === 'element' && node.className ? [[node.id, node.className]] : [])));
-    const unknown = await unknownClasses({ tokens: expanded.document.tokens, css: expanded.document.css, byNode: own, base: PACKAGE_ROOT });
-    return { document, html, fileHtml: renderFile(expanded.document, { compiledCss, parts: expanded.parts, instances, limits }), uses: expanded.uses, unknown };
+/** The Node composition: the installed style engine compiles each frame's classes. */
+const engineCompiler = {
+    compile: (tokens, candidates) => compileClasses(tokens, candidates, PACKAGE_ROOT),
+    unknown: input => unknownClasses({ ...input, base: PACKAGE_ROOT }),
+};
+export function prepareFrame(input, { lookup = () => undefined, settings = null, limits = LIMITS } = {}) {
+    return prepareFrameWith(input, { lookup, settings, limits, compiler: engineCompiler });
 }
 /** The `meta.json` beside a generated page: what it was built from, what it depends on and the hashes that detect a rebuild. */
 export function frameMetadata(entry, entries, projectFile) {

package/dist/core/lib/runtime.d.ts

@@ -323,7 +323,7 @@ export class DivletRuntime extends EventEmitter<[never]> {
     prepare(input: any, { frames, settings, limits }?: {
         settings?: import("./project.ts").ProjectSettings | undefined;
         limits?: Readonly<import("./model.ts").Limits> | undefined;
-    }): Promise<import("./render.ts").PreparedFrame>;
+    }): Promise<import("./prepare.ts").PreparedFrame>;
     /** A board entry for a prepared frame; the render counter only moves when the preview changes. */
     entryFor(prepared: any, previous: any, outputDir?: string): any;
     /** Frames that must re-render when `ids` change (they use components from them). */

package/dist/core/lib/runtime.js

@@ -13,6 +13,7 @@ import { buildSite } from "./site.js";
 import { diffDocuments, diffValue, matchesPatch, summarizeChange, touchedNodeIds } from "./diff.js";
 import { operationPatch } from "./ops.js";
 import { HistoryLine } from "./history.js";
+import { SETTINGS_FIELDS, sameDocument, sameSettings, settingsPatch, assertExpectedVersion, assertExpectedRender } from "./acceptance.js";
 import { expandPath, inspectPath, initProject, resolveProject, isProjectFile } from "./projects.js";
 import { OutputStore, safeDirectory } from "./output.js";
 import { buildStatic, inlineDeclaredAssets, readResourceBytes, normalizeExternalFiles } from './static.js';
@@ -35,7 +36,6 @@ const MAX_ASK = 4000;
 const MAX_REPLY = 6000;
 const HISTORY_LIMIT = 500;
 const UNDO_LIMIT = 200;
-const SETTINGS_FIELDS = ['name', 'tokens', 'css', 'metadata', 'outputDir', 'assets'];
 const capped = (list, limit = 50) => list.slice(0, limit);
 const digest = value => createHash('sha256').update(value).digest('hex');
 const hashOf = text => (text === null || text === undefined ? null : digest(text));
@@ -52,9 +52,6 @@ const imageUpload = (name, data, mediaType) => {
         fail('UNSUPPORTED_ASSET', 'The upload must declare a supported canonical image media type.');
     return { extension, mediaType: type, bytes: Buffer.from(data) };
 };
-const sameDocument = (a, b) => isDeepStrictEqual({ ...a, version: 0 }, { ...b, version: 0 });
-const sameSettings = (a, b) => SETTINGS_FIELDS.every(key => isDeepStrictEqual(a[key], b[key]));
-const settingsPatch = (from, to) => Object.fromEntries(SETTINGS_FIELDS.map(key => [key, diffValue(from[key], to[key])]).filter(([, value]) => value !== undefined));
 const inside = (root, target) => target === root || (!path.relative(root, target).startsWith('..' + path.sep) && path.relative(root, target) !== '..' && !path.isAbsolute(path.relative(root, target)));
 function fail(code, message, details) {
     throw new DivletError(code, message, details);
@@ -91,23 +88,6 @@ function styleWarnings({ unknown = {}, changed = [], css = null, where }) {
     }
     return out;
 }
-/**
- * A caller that names the state it read gets a refusal instead of silently overwriting a change it
- * never saw (AGENTS.md, "Validated commits"). Omitted means the caller accepted whatever is current.
- */
-function assertExpectedVersion(expected, target, what = 'frame') {
-    if (expected === undefined)
-        return;
-    if (!Number.isInteger(expected) || expected !== target.version)
-        fail('REVISION_CONFLICT', `Expected ${what} version ${target.version}; received ${expected}. Read it again and rebuild the change.`, { actualVersion: target.version });
-}
-/** The rendered page a gesture was made against; a dependent re-render advances it without a version bump. */
-function assertExpectedRender(expected, entry) {
-    if (expected === undefined)
-        return;
-    if (!Number.isInteger(expected) || expected !== entry.render)
-        fail('RENDER_CONFLICT', `Expected frame render ${entry.render}; received ${expected}. The page changed since it was read; reload the frame and repeat the change.`, { actualRender: entry.render, actualVersion: entry.document.version });
-}
 /*
  * Each .divlet file is an independent source of truth. Generated pages and metadata belong
  * to its OutputStore, by default .divlet/<source filename stem> beside that source file.

package/dist/core/lib/tools.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The host-neutral schema. A tool's parameters are written once in this form; each host renders it — Pi as TypeBox, MCP as
+ * JSON Schema — so a plugin or adapter that adds a tool describes it here and nowhere else.
+ */
+interface SchemaBase {
+    optional?: boolean;
+    description?: string;
+}
+export type Schema = (SchemaBase & {
+    kind: 'string';
+    maxLength?: number;
+    minLength?: number;
+}) | (SchemaBase & {
+    kind: 'integer';
+    minimum?: number;
+    maximum?: number;
+}) | (SchemaBase & {
+    kind: 'number';
+    minimum?: number;
+    maximum?: number;
+}) | (SchemaBase & {
+    kind: 'boolean';
+}) | (SchemaBase & {
+    kind: 'oneOf';
+    values: readonly string[];
+}) | (SchemaBase & {
+    kind: 'object';
+    properties: Record<string, Schema> | null;
+}) | (SchemaBase & {
+    kind: 'array';
+    items: Schema;
+    maxItems?: number;
+}) | (SchemaBase & {
+    kind: 'union';
+    variants: Schema[];
+}) | (SchemaBase & {
+    kind: 'any';
+}) | (SchemaBase & {
+    kind: 'null';
+});
+/** One tool's parameters, by name. */
+export type ToolParameters = Record<string, Schema>;
+/** JSON Schema as a host asks for it (the shape MCP `tools/list` answers). */
+export type JsonSchema = Record<string, any>;
+/** A host-neutral schema: the tool list is written once, Pi and MCP render it. */
+export declare const S: {
+    string: (options?: Omit<Extract<Schema, {
+        kind: "string";
+    }>, "kind">) => Schema;
+    integer: (options?: Omit<Extract<Schema, {
+        kind: "integer";
+    }>, "kind">) => Schema;
+    number: (options?: Omit<Extract<Schema, {
+        kind: "number";
+    }>, "kind">) => Schema;
+    boolean: (options?: Omit<Extract<Schema, {
+        kind: "boolean";
+    }>, "kind">) => Schema;
+    /** One of a fixed set of strings. */
+    oneOf: (values: readonly string[], options?: Omit<Extract<Schema, {
+        kind: "oneOf";
+    }>, "kind" | "values">) => Schema;
+    /** An object with these properties (`null` shape: any object). */
+    object: (properties?: Record<string, Schema> | null, options?: Omit<Extract<Schema, {
+        kind: "object";
+    }>, "kind" | "properties">) => Schema;
+    array: (items: Schema, options?: Omit<Extract<Schema, {
+        kind: "array";
+    }>, "kind" | "items">) => Schema;
+    union: (variants: Schema[], options?: Omit<Extract<Schema, {
+        kind: "union";
+    }>, "kind" | "variants">) => Schema;
+    any: (options?: Omit<Extract<Schema, {
+        kind: "any";
+    }>, "kind">) => Schema;
+};
+export declare const optional: (schema: Schema) => Schema;
+export declare const nullable: (schema: Schema) => Schema;
+/** A JSON Schema property for one parameter (the shape MCP asks for). */
+export declare function propertySchema(schema: Schema): JsonSchema;
+/** The `inputSchema` of a tool for MCP (`tools/list`). */
+export declare function inputSchema(tool: Tool): JsonSchema;
+/** The subset of TypeBox a host needs to render the schema; the Pi adapter passes the real module. */
+export interface TypeBoxApi {
+    String(options?: Record<string, unknown>): unknown;
+    Integer(options?: Record<string, unknown>): unknown;
+    Number(options?: Record<string, unknown>): unknown;
+    Boolean(options?: Record<string, unknown>): unknown;
+    Literal(value: string): unknown;
+    Union(items: unknown[]): unknown;
+    Object(properties: Record<string, unknown>, options?: Record<string, unknown>): unknown;
+    Record(key: unknown, value: unknown): unknown;
+    Array(items: unknown, options?: Record<string, unknown>): unknown;
+    Null(): unknown;
+    Unknown(): unknown;
+    Optional(item: unknown): unknown;
+}
+/** The same schema as TypeBox types, for the Pi extension. */
+export declare function toTypeBox(schema: ToolParameters, Type: TypeBoxApi): unknown;
+export declare const LARGE_FRAME_BYTES = 60000;
+/** Rename document → frame in tool results, leaving user data (node maps, metadata…) untouched. */
+export declare function forAgent(value: unknown, key?: string): unknown;
+/** The project view for an agent: what it needs to choose a frame, without file paths and without one line per use. */
+export declare function compactProject(info: any): any;
+/** Components with their name and overridable texts, only the first few places used and a count. */
+export declare function compactComponents(result: any): any;
+/** An outline of a frame model: ids, tags, names and the start of text, three levels deep, with counts where it is cut. */
+export declare function outlineOf(model: any, bytes: number): Record<string, unknown>;
+/** What a tool may ask of the board it runs on. `any` results are the runtime's own shapes, shaped for agents below. */
+export interface BoardRuntime {
+    info(): any;
+    read(query: Record<string, unknown>): any;
+    patch(args: Record<string, unknown>): Promise<any>;
+    edit(args: Record<string, unknown>): Promise<any>;
+    undo(args: Record<string, unknown>): Promise<any>;
+    redo(args: Record<string, unknown>): Promise<any>;
+    create(args: Record<string, unknown>): Promise<any>;
+    getEntry(documentId: string): any;
+    render(documentId: string): any;
+    createArtboard(args: Record<string, unknown>): Promise<any>;
+    removeDocument(args: Record<string, unknown>): Promise<any>;
+    frame(args: Record<string, unknown>): Promise<any>;
+    mark(args: Record<string, unknown>): any;
+    close(): Promise<void>;
+    [key: string]: any;
+}
+/** The context a tool runs with: the board that owns the project. */
+export interface ToolContext {
+    runtime: BoardRuntime;
+}
+/** One capability: named, described and parameterised once, rendered by every host. */
+export interface Tool {
+    name: string;
+    /** Short human title (absent on hidden tools). */
+    title?: string;
+    kind: 'open' | 'runtime';
+    description: string;
+    /** One line a host may advertise instead of the description. */
+    snippet?: string;
+    hidden?: boolean;
+    parameters: ToolParameters;
+    /** Absent for `open_divlet`, which the session handles itself. */
+    run?(context: ToolContext, params: any): any;
+}
+/** A runtime is required for every tool but `open_divlet`; the session resolves it before running one. */
+export declare const TOOLS: Tool[];
+export declare const toolByName: ReadonlyMap<string, Tool>;
+export declare const toolList: ({ hidden }?: {
+    hidden?: boolean;
+}) => Tool[];
+export declare const toolNames: Set<string>;
+/** Run one runtime tool against a board's runtime (used by the session and by the board's own api/tool route). */
+export declare function runOnRuntime(name: string, args: unknown, runtime: BoardRuntime): Promise<any>;
+export {};