@psrt/sdk 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @psrt/sdk
 
-Stateless PSRT SDK powered by WebAssembly (Go core).
+TypeScript library for parsing, editing, and compiling PSRT documents.
 
 ## Install
 
@@ -10,28 +10,67 @@ npm install @psrt/sdk
 
 ## Usage
 
+Call `initPsrt()` once at startup, then use the API:
+
 ```typescript
-import { initPsrt, parse, compileToHtml, adaptEntriesForWeb } from '@psrt/sdk'
+import { readFileSync } from 'node:fs'
+import { initPsrt, parse, compileToHtml, compileToSvg } from '@psrt/sdk'
 
-await initPsrt('/path/to/psrt.wasm')
+await initPsrt()
 
+const psrtString = readFileSync('document.psrt', 'utf8')
 const doc = parse(psrtString)
+
 const html = compileToHtml(doc)
-const styles = adaptEntriesForWeb(JSON.stringify(entries), 800, 600, 1)
+const svg = compileToSvg(doc, doc.pages[0]!.name)
 ```
 
-## Browser (Vite)
+`initPsrt()` is idempotent — safe to call more than once, but one call at app entry is enough.
 
-Copy `wasm/psrt.wasm` and `wasm/wasm_exec.js` to your `public/` folder, then:
+## Editor (fluent API)
 
 ```typescript
-await initPsrt(`${import.meta.env.BASE_URL}wasm/psrt.wasm`)
+import { initPsrt, parse, stringify, transform } from '@psrt/sdk'
+
+await initPsrt()
+
+const doc = parse(psrtString)
+const pageName = doc.pages[0]!.name
+
+const updated = transform(doc)
+  .addText(pageName, {
+    x: 10,
+    y: 20,
+    width: 100,
+    textSize: 2,
+    index: 1,
+    content: 'Hello',
+    style: {},
+  })
+  .build()
+
+const out = stringify(updated)
+```
+
+## Live preview styles
+
+```typescript
+import { initPsrt, adaptEntriesForWeb } from '@psrt/sdk'
+
+await initPsrt()
+
+const styles = adaptEntriesForWeb(entriesJSON, canvasWidth, canvasHeight, zoom)
 ```
 
 ## Exports
 
-- **I/O:** `parse`, `stringify`, `formatDocument`, `resolveDocument`
+- **Init:** `initPsrt`
+- **I/O:** `parse`, `stringify`, `formatDocument`, `resolveDocument`, `resolveDocumentStrict`
 - **Compile:** `compileToHtml`, `compileToSvg`
-- **Preview:** `adaptEntriesForWeb`
+- **Preview:** `adaptEntriesForWeb`, `formatPageDocumentJSON`, `mergePageDocumentPSRT`
 - **Editor:** `addText`, `setTextContent`, `transform`, …
 - **Types:** `PsrtDocument`, `Document`, `Page`, `TextBlock`, …
+
+## React
+
+See [@psrt/react-image](../react-image/README.md). Call `initPsrt()` once in your app entry before rendering.

package/dist/browser/index.d.ts

@@ -0,0 +1,260 @@
+/** Initializes PSRT. Call once at app startup before any other SDK API. */
+declare function initPsrt(): Promise<void>;
+
+declare const CompileStep: {
+    readonly RESOLVE: "resolve";
+    readonly BUILD_ASSETS: "buildAssets";
+    readonly ADAPT_STYLE: "adaptStyle";
+    readonly RENDER_FONTS: "renderFonts";
+    readonly RENDER_HEAD: "renderHead";
+    readonly RENDER_PAGE: "renderPage";
+    readonly RENDER_TEXT: "renderText";
+    readonly RENDER_MASK: "renderMask";
+    readonly RENDER_INLINE: "renderInline";
+    readonly FINALIZE: "finalize";
+};
+type CompileStep = (typeof CompileStep)[keyof typeof CompileStep];
+type CompileStepContext = {
+    step: typeof CompileStep.RESOLVE;
+    doc: PsrtDocument;
+} | {
+    step: typeof CompileStep.BUILD_ASSETS;
+    assetCount: number;
+    canvasSizes: Record<string, {
+        w: number;
+        h: number;
+    }>;
+} | {
+    step: typeof CompileStep.ADAPT_STYLE;
+    pageName: string;
+    blockIndex: number;
+    kind: 'text' | 'mask';
+} | {
+    step: typeof CompileStep.RENDER_FONTS;
+    fontCount: number;
+} | {
+    step: typeof CompileStep.RENDER_HEAD;
+    title: string;
+} | {
+    step: typeof CompileStep.RENDER_PAGE;
+    pageIndex: number;
+    pageName: string;
+    canvasW: number;
+    canvasH: number;
+} | {
+    step: typeof CompileStep.RENDER_TEXT;
+    pageName: string;
+    textIndex: number;
+    contentPreview: string;
+} | {
+    step: typeof CompileStep.RENDER_MASK;
+    pageName: string;
+    maskIndex: number;
+} | {
+    step: typeof CompileStep.RENDER_INLINE;
+    pageName: string;
+    textIndex: number;
+    htmlLength: number;
+} | {
+    step: typeof CompileStep.FINALIZE;
+    htmlLength: number;
+    pageCount: number;
+};
+type CompileStepObserver = (ctx: CompileStepContext) => void;
+type CompileStepObservers = Partial<Record<CompileStep, CompileStepObserver[]>>;
+declare function notifyObservers(observers: CompileStepObservers | undefined, ctx: CompileStepContext): void;
+
+/** JSON object or compact style string from PSRT. */
+type PsrtStyle = Record<string, unknown> | string;
+/** Canonical PSRT document representation. */
+interface PsrtDocument {
+    pages: PsrtPage[];
+    fonts: string[];
+    consts: Record<string, string>;
+}
+type Document = PsrtDocument;
+interface PsrtPage {
+    name: string;
+    style: PsrtStyle;
+    imageUrl: string;
+    texts: PsrtText[];
+    masks?: PsrtMask[];
+}
+type Page = PsrtPage;
+interface PsrtText {
+    x: number;
+    y: number;
+    width: number;
+    textSize: number;
+    style: PsrtStyle;
+    index: number;
+    content: string;
+    imageRef?: string;
+}
+/** PSRT text block (>> header), not editor UI model. */
+type TextBlock = PsrtText;
+interface PsrtMask {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    style: PsrtStyle;
+    index: number;
+    imageRef?: string;
+}
+interface PositionFields {
+    x?: number;
+    y?: number;
+    width?: number;
+    textSize?: number;
+}
+interface MaskPositionFields {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+}
+interface CompileOptions {
+    /** Keep original asset URLs instead of embedding data URIs. */
+    linksOnly?: boolean;
+    /** Omit the HTML variant switcher script (Ctrl+L). */
+    noScript?: boolean;
+}
+interface CompileToHtmlPureOptions extends CompileOptions {
+    observers?: CompileStepObservers;
+    /** Additional PSRT variants bundled into the same HTML (Ctrl+L to switch). */
+    variants?: PsrtVariant[];
+}
+/** One PSRT document bundled as an HTML variant alongside the primary doc. */
+interface PsrtVariant {
+    /** Label shown in the variant switcher hint (defaults to variant-N). */
+    label?: string;
+    doc: PsrtDocument;
+}
+
+/** Converts a .psrt string into a typed PsrtDocument. */
+declare function parse(psrtString: string): PsrtDocument;
+/** Converts a PsrtDocument back to normative .psrt text. */
+declare function stringify(doc: PsrtDocument): string;
+/** Formats a document with editor cleanup rules. */
+declare function formatDocument(doc: PsrtDocument): string;
+
+/** Expands all @const@ placeholders in styles, content, and URLs. */
+declare function resolveDocumentPure(doc: PsrtDocument): PsrtDocument;
+
+/** Compiles the document to a self-contained HTML string (WASM). */
+declare function compileToHtml(doc: PsrtDocument | string, options?: CompileOptions): string;
+/** Compiles PsrtDocument to HTML using pure JavaScript (no WASM, no initPsrt). */
+declare function compileToHtmlPure(doc: PsrtDocument, options?: CompileToHtmlPureOptions): string;
+
+/** Compiles one page of the document to SVG. */
+declare function compileToSvg(doc: PsrtDocument | string, pageName: string, options?: CompileOptions): string;
+
+/** Fluent builder for chained PSRT document edits. */
+declare class Transformer {
+    private _doc;
+    constructor(input: PsrtDocument | string);
+    /** Read-only view of the current document state. */
+    get document(): Readonly<PsrtDocument>;
+    addConst(name: string, value: string): this;
+    removeConst(name: string): this;
+    substituteConstReferences(name: string, value: string): this;
+    revertConstReferences(name: string, value: string): this;
+    addFont(url: string): this;
+    removeFont(url: string): this;
+    renamePage(oldName: string, newName: string): this;
+    setPagePath(pageName: string, path: string): this;
+    setPageStyle(pageName: string, key: string, value: string, partial?: PsrtStyle): this;
+    removePageStyleKey(pageName: string, key: string): this;
+    movePage(pageName: string, before?: string, after?: string): this;
+    addPage(page: PsrtPage, before?: string, after?: string): this;
+    removePage(name: string): this;
+    setTextStyle(pageName: string, textIndex: number, key: string, value: string, partial?: PsrtStyle): this;
+    removeTextStyleKey(pageName: string, textIndex: number, key: string): this;
+    setTextContent(pageName: string, index: number, content: string, appendContent?: boolean): this;
+    addText(pageName: string, text: PsrtText, opts?: {
+        beforeIndex?: number;
+        afterIndex?: number;
+    }): this;
+    removeText(pageName: string, textIndex: number): this;
+    reorderTextRelative(pageName: string, textIndex: number, beforeIndex?: number, afterIndex?: number): this;
+    reorderTextTo(pageName: string, textIndex: number, to: number): this;
+    reorderTextByDelta(pageName: string, textIndex: number, delta: number): this;
+    setTextPosition(pageName: string, textIndex: number, pos: PositionFields): this;
+    nudgeTextPosition(pageName: string, textIndex: number, delta: PositionFields): this;
+    setMaskPosition(pageName: string, maskIndex: number, pos: MaskPositionFields): this;
+    addMask(pageName: string, mask: PsrtMask, opts?: {
+        beforeIndex?: number;
+        afterIndex?: number;
+    }): this;
+    removeMask(pageName: string, maskIndex: number): this;
+    setMaskStyle(pageName: string, maskIndex: number, key: string, value: string, partial?: PsrtStyle): this;
+    removeMaskStyleKey(pageName: string, maskIndex: number, key: string): this;
+    /** Returns the accumulated document after the edit chain. */
+    build(): PsrtDocument;
+    /** Shortcut: build() + stringify(). */
+    buildPsrt(): string;
+}
+declare function transform(input: PsrtDocument | string): Transformer;
+
+interface WebPreviewStyle {
+    container: Record<string, string>;
+    text: Record<string, string>;
+    hasStroke: boolean;
+}
+/** Adapts text/mask entries for live web preview CSS (percent → px, stroke → WebKit, etc.). */
+declare function adaptEntriesForWeb(entriesJSON: string, canvasW: number, canvasH: number, zoom: number): WebPreviewStyle[];
+/** Applies a page PSRT fragment into a full document. */
+declare function mergePageDocumentPSRT(fullDocJSON: string, pageName: string, psrtText: string): PsrtDocument;
+/** Formats one page plus document fonts and constants as PSRT text. */
+declare function formatPageDocumentJSON(docJSON: string, pageName: string): string;
+
+declare function addConst(doc: PsrtDocument, name: string, value: string): PsrtDocument;
+declare function removeConst(doc: PsrtDocument, name: string): PsrtDocument;
+declare function substituteConstReferences(doc: PsrtDocument, name: string, value: string): PsrtDocument;
+declare function revertConstReferences(doc: PsrtDocument, name: string, value: string): PsrtDocument;
+
+declare function addFont(doc: PsrtDocument, url: string): PsrtDocument;
+declare function removeFont(doc: PsrtDocument, url: string): PsrtDocument;
+
+declare function renamePage(doc: PsrtDocument, oldName: string, newName: string): PsrtDocument;
+declare function setPagePath(doc: PsrtDocument, pageName: string, path: string): PsrtDocument;
+declare function setPageStyle(doc: PsrtDocument, pageName: string, key: string, value: string, partial?: PsrtStyle): PsrtDocument;
+declare function removePageStyleKey(doc: PsrtDocument, pageName: string, key: string): PsrtDocument;
+declare function movePage(doc: PsrtDocument, pageName: string, before?: string, after?: string): PsrtDocument;
+declare function addPage(doc: PsrtDocument, page: PsrtPage, before?: string, after?: string): PsrtDocument;
+declare function removePage(doc: PsrtDocument, name: string): PsrtDocument;
+
+declare function setTextStyle(doc: PsrtDocument, pageName: string, textIndex: number, key: string, value: string, partial?: PsrtStyle): PsrtDocument;
+declare function removeTextStyleKey(doc: PsrtDocument, pageName: string, textIndex: number, key: string): PsrtDocument;
+declare function setTextContent(doc: PsrtDocument, pageName: string, index: number, newContent: string, appendContent?: boolean): PsrtDocument;
+declare function addText(doc: PsrtDocument, pageName: string, text: PsrtText, beforeIndex?: number, afterIndex?: number): PsrtDocument;
+declare function removeText(doc: PsrtDocument, pageName: string, textIndex: number): PsrtDocument;
+declare function reorderTextRelative(doc: PsrtDocument, pageName: string, textIndex: number, beforeIndex?: number, afterIndex?: number): PsrtDocument;
+declare function reorderTextTo(doc: PsrtDocument, pageName: string, textIndex: number, to: number): PsrtDocument;
+declare function reorderTextByDelta(doc: PsrtDocument, pageName: string, textIndex: number, delta: number): PsrtDocument;
+declare function setTextPosition(doc: PsrtDocument, pageName: string, textIndex: number, pos: PositionFields): PsrtDocument;
+declare function nudgeTextPosition(doc: PsrtDocument, pageName: string, textIndex: number, delta: PositionFields): PsrtDocument;
+
+declare function setMaskPosition(doc: PsrtDocument, pageName: string, maskIndex: number, pos: MaskPositionFields): PsrtDocument;
+declare function addMask(doc: PsrtDocument, pageName: string, mask: PsrtMask, beforeIndex?: number, afterIndex?: number): PsrtDocument;
+declare function removeMask(doc: PsrtDocument, pageName: string, maskIndex: number): PsrtDocument;
+declare function setMaskStyle(doc: PsrtDocument, pageName: string, maskIndex: number, key: string, value: string, partial?: PsrtStyle): PsrtDocument;
+declare function removeMaskStyleKey(doc: PsrtDocument, pageName: string, maskIndex: number, key: string): PsrtDocument;
+
+declare function setStyleKey(style: PsrtStyle, key: string, value: string): PsrtStyle;
+declare function removeStyleKey(style: PsrtStyle, key: string): PsrtStyle;
+declare function mergeStyle(style: PsrtStyle, partial: PsrtStyle): PsrtStyle;
+
+declare function findPage(doc: PsrtDocument, name: string): PsrtPage;
+declare function findPageIndex(doc: PsrtDocument, name: string): number;
+declare function findTextByIndex(doc: PsrtDocument, pageName: string, index: number): PsrtText;
+declare function findMaskByIndex(doc: PsrtDocument, pageName: string, index: number): PsrtMask;
+declare function parseTextIndex(s: string): number;
+
+/** Expands all @const@ placeholders in styles, content, and URLs. */
+declare function resolveDocument(doc: PsrtDocument): PsrtDocument;
+/** Like resolveDocument but throws on invalid style JSON after expansion. */
+declare function resolveDocumentStrict(doc: PsrtDocument): PsrtDocument;
+
+export { type CompileOptions, CompileStep, type CompileStepContext, type CompileStepObserver, type CompileStepObservers, type CompileToHtmlPureOptions, type Document, type MaskPositionFields, type Page, type PositionFields, type PsrtDocument, type PsrtMask, type PsrtPage, type PsrtStyle, type PsrtText, type PsrtVariant, type TextBlock, Transformer, type WebPreviewStyle, adaptEntriesForWeb, addConst, addFont, addMask, addPage, addText, compileToHtml, compileToHtmlPure, compileToSvg, findMaskByIndex, findPage, findPageIndex, findTextByIndex, formatDocument, formatPageDocumentJSON, initPsrt, mergePageDocumentPSRT, mergeStyle, movePage, notifyObservers, nudgeTextPosition, parse, parseTextIndex, removeConst, removeFont, removeMask, removeMaskStyleKey, removePage, removePageStyleKey, removeStyleKey, removeText, removeTextStyleKey, renamePage, reorderTextByDelta, reorderTextRelative, reorderTextTo, resolveDocument, resolveDocumentPure, resolveDocumentStrict, revertConstReferences, setMaskPosition, setMaskStyle, setPagePath, setPageStyle, setStyleKey, setTextContent, setTextPosition, setTextStyle, stringify, substituteConstReferences, transform };