diff --git a/RELEASE_NOTES/v0.8.2.md b/RELEASE_NOTES/v0.8.2.md index aa5a5e970..4a20ccd1d 100644 --- a/RELEASE_NOTES/v0.8.2.md +++ b/RELEASE_NOTES/v0.8.2.md @@ -1,74 +1,351 @@ # OpenPencil v0.8.2 -`v0.8.2` is a prerelease focused on higher-fidelity imports, lower transient -memory use, smoother large-document workflows, and safer `.op` persistence. +`v0.8.2` is a prerelease focused on higher-fidelity Figma and HTML imports, +lower transient memory use, smoother large-document workflows, safer `.op` +persistence, and backward-compatible schema evolution. + +This update expands both the data OpenPencil can preserve and the controls +available for editing that data. It also separates expensive conversion and +save work from the interactive UI, tightens overwrite behavior, and documents +where memory is reduced versus where the complete canonical document must +still remain available. ## Highlights -- Figma imports more closely preserve component instances and swaps, masks, - blend modes, page backgrounds, tiled images, vectors, text, child order, and - absolute positioning. -- Desktop Figma conversion runs outside the UI thread and writes a sibling - `.op` file. An existing target is never silently overwritten: replace it, - keep both with a numbered copy, or cancel the import. -- Large documents use a focused active-page render scene. Switching pages - releases the previous scene, then fits and centers the newly active page. -- Desktop Save and Save As run as serialized background jobs, reducing UI - stalls and avoiding unnecessary full-document clones for clean files. -- Older `.op` files open through the compatibility loader and can be upgraded - in place, saved as a numbered copy, or opened without conversion. -- HTML import now accepts complete pages, multi-file projects, and ZIP packages - with local CSS, images, nested imports, and common text encodings. +- Figma imports preserve substantially more of the authored component, + geometry, compositing, image, text, and page data that previously required + flattening or approximation. +- Component instances keep their backing component information, instance + properties, swap targets, overrides, authored geometry, and style + references. +- Masks, layer and fill blend modes, image tiling, and page backgrounds now + round-trip through the schema, renderer, web host, and property inspector. +- Desktop conversion runs outside the UI thread and reuses prepared values, + source text metrics, image lookups, instance assignments, and component + style references. +- Large documents use an active-page editor scene. Native page switching drops + the previous scene before building the next; native and web both fit and + center the newly active page. +- Desktop Save and Save As run as serialized background jobs, while native + publication uses atomic writes and source revalidation. +- Known legacy `.op` formats can be upgraded in place, saved as a numbered + copy, or opened without modifying the file on disk. +- HTML import accepts complete pages, multi-file projects, and ZIP packages + with local resources, nested CSS imports, and common text encodings. -## Figma and Editing Fidelity +## Figma Import Fidelity -- Component properties, instance overrides, swap targets, authored geometry, - and style references survive conversion more reliably. -- Alpha, vector, and luminance masks, layer and fill blend modes, image tile - scale, and page background color render on native and web surfaces and are - configurable in the property inspector. -- Boolean geometry, vector bounds, image fills, text measurement, layout - positioning, and paint order more closely match the source design. +### Components, Instances, and Swaps -## Performance and Reliability +- Component property definitions are retained as structured component backing + data instead of being reduced to only the visible instance result. +- Instance property assignments and overrides keep their relationship to the + backing component so later edits can distinguish inherited and authored + values. +- Instance-swap properties preserve the selected component target and filter + invalid candidates instead of silently substituting unrelated symbols. +- Swapped subtrees retain their authored size, transform, paint, and style + references. Instance scaling is restricted to component-space branches so it + does not rescale ordinary descendants a second time. +- Foreign and nested component sessions reuse resolved assignments and style + information, reducing differences between repeated instances of the same + source component. +- The property inspector exposes component and swap configuration for imported + instances instead of leaving the imported metadata inaccessible. -- Figma conversion reuses prepared values, text measurements, image lookups, - and component data instead of recomputing them for every node. -- Desktop `.op` loading uses memory-mapped input and a fast path for safe - Preserve-mode documents. -- Web Figma conversion runs in a short-lived worker with IndexedDB staging, so - conversion memory can be released before the document is installed in the - editor. -- Native publication is atomic, web saves are queued and coalesced, and an - externally changed target is preserved by falling back to a numbered copy. -- Windows desktop startup recovers when the preferred native OpenGL path is - unavailable. +### Geometry, Layout, and Text -## Compatibility +- Authored absolute positioning is preserved for layers that should not be + reflowed by an inferred container layout. +- Child order and paint order follow the Figma source more closely, including + mixed container, vector, and mask content. +- Boolean operations recover usable child geometry when the preferred result + stream is empty, while genuinely empty geometry stays invisible instead of + becoming a filled placeholder block. +- Expanded strokes, open vector networks, fill rules, vector bounds, rounded + vertices, and squircle-like smoothing have more accurate fallbacks. +- Image-fill transforms and crop geometry are applied when mapping source + images into their authored bounds. +- Source text metrics and baselines are reused consistently, while temporary + glyph, baseline, and font-resolution caches are released after their import + stage. +- Text, vectors, image fills, and layout positioning now share more of the same + resolved geometry between interactive rendering and export paths. + +### Masks, Compositing, Images, and Pages + +- Alpha, vector, and luminance masks render through the shared native and web + paint model. +- Layer blend modes and individual fill blend modes are represented separately + so compositing does not need to be flattened into a single approximation. +- Page background color is preserved in the document and can be edited from + the page section of the property inspector. +- Tiled image fills keep their tile scale, while cropped and transformed image + fills retain the source mapping needed for closer visual parity. +- Image resolution deduplicates repeated references and transformed assets + instead of decoding or embedding the same source for every occurrence. +- The property inspector adds the previously missing controls for masks, + compositing, image tiling, page backgrounds, and component-instance data. +- New schema fields are optional, so v0.8.2 can continue reading older + documents and TypeScript object literals that omit them. This does not claim + that every older OpenPencil version can read every v0.8.2 document. + +## Figma Conversion Performance + +- Import preparation decodes and normalizes reusable source values once before + node conversion begins. +- Figma-provided text metrics are reused across the relevant conversion stage, + and glyph, baseline, and font-resolution scratch data is released when that + stage completes. +- Image lookup and decoded-image work are shared across repeated image + references and instance subtrees. +- Component resolution caches instance assignments, swap decisions, style + references, and prepared component data. +- The component registry keeps shallow lookup metadata instead of cloning every + master subtree into a second document-sized registry. +- Image caches are budgeted by decoded bytes rather than only by entry count, + preventing a handful of very large images from bypassing the cache limit. +- Shared image assets are deduplicated into the document image table on save + paths instead of being repeated by each consumer. +- Desktop conversion runs in a background import session while the UI + continues processing input and repaint work. Cancellation prevents later + stages and result installation; an already-running, non-interruptible decode + finishes before its worker exits. +- Heavy conversion workers are serialized so cancelling and starting another + import does not intentionally overlap two peak conversion workloads. +- Large conversion payloads use shared or indirect ownership where possible, + reducing queue copies and temporary allocation amplification. +- After a successful desktop conversion, the proposed `.op` output sits beside + the imported `.fig` source instead of being kept only in a temporary + directory. +- If that sibling `.op` already exists, OpenPencil asks before replacing it. + Replacing, keeping both with a numbered copy, and cancelling the import are + separate user choices. A detected existing target is not replaced without + that decision. + +## Large Documents, Memory, and Page Switching + +- Desktop `.op` loading memory-maps the source instead of first copying the + complete file into a second byte buffer. +- Preserve-authored documents use a fast loader after validating that the + current shape is safe, avoiding the generic full compatibility DOM on the + common path. +- The interactive native and web editor scenes materialize the active page + rather than building render trees for every page at once. +- On native page switches, the previous page scene is dropped before the next + scene is built. The web host rebuilds and replaces the active scene. +- Switching to a different page automatically fits and centers that page. + Selecting the already active page does not unexpectedly reset the current + viewport. +- Non-active pages remain available to the editor but do not keep a full + interactive render scene alive. +- This is scene-level memory reduction, not document-level page streaming. The + canonical document still retains the data for every page while the file is + open. +- Import, save, and clean-copy paths use streaming or indirection where + practical to reduce duplicated buffers, queue size, and peak transient + allocations. + +## `.op` Saving and Overwrite Safety + +- Desktop Save and Save As are serialized background jobs, preventing + overlapping publications from blocking the UI or committing out of order. +- A clean document already bound to a source can stream the original bytes and + rewrite only embedded editor metadata instead of cloning and serializing the + complete canonical document again. +- Native writes use an atomic sibling temporary file and publish the + destination only after the new payload has been written successfully. +- Desktop Figma sibling publication and legacy-upgrade replacement record the + relevant source or target identity before confirmation and revalidate it + before the final atomic replacement. +- If those guarded paths detect an external change before that final check, + OpenPencil preserves the changed file and publishes a numbered copy instead. + The final atomic replacement prevents a partially written destination, but + it is not described as an operating-system-level compare-and-swap. +- Generated desktop Figma sibling `.op` files use the same explicit overwrite + decision and numbered-copy behavior as migrated desktop documents. +- Failed serialization, migration, or publication does not bind stale + in-memory state to a path that was not successfully written. +- Save completion is checked against the document generation and revision that + started the job, so a late acknowledgement cannot mark newer edits as clean. +- Web saves use a queue and coalesce superseded work so an older serialization + cannot publish after a newer edit. + +## Legacy `.op` Upgrade and Compatibility - The current `.op` format marker is `1.2`. -- Legacy upgrades preserve unknown top-level and nested fields; new optional - schema fields and generated TypeScript bindings remain backward compatible. +- Desktop upgrade prompts are shown only after a document loads successfully + and needs a known wire-format repair, reliable editor-metadata inference, or + adoption of a legacy metadata sidecar. - A current-format document does not trigger migration merely because optional editor metadata is absent. -- Active-page rendering reduces renderer memory, but the canonical document - still retains all page data while it is open. -- Future incompatible format majors are rejected instead of being rewritten. -- OpenPencil account sign-in is temporarily hidden in this prerelease and is - planned to return in a later version. -- The public web SDK remains a read-only viewer surface, and the retired - TypeScript application workspace is not part of this release. +- The upgrade prompt provides three explicit outcomes: + - upgrade and replace the original; + - keep the original and write a numbered `.op` copy; + - open the repaired in-memory document without changing the file on disk. +- Migration starts from the raw document representation so unknown top-level + and nested fields survive a successful rewrite. +- Deeply nested documents use stack-protected decode and encode paths, avoiding + stack exhaustion during compatibility repair. +- Successful migration writes the current format marker and embedded editor + metadata. Replacing the original removes its obsolete sidecar only after a + successful commit. +- Writing a numbered copy leaves the original file and its sidecar unchanged; + the new copy contains embedded editor metadata and does not adopt a stale + sidecar for the copy path. +- Malformed version markers, unsupported very old integer-version payloads, + and future incompatible format majors are rejected instead of being guessed, + normalized, or overwritten. +- If migration cannot be published safely, OpenPencil does not install a + misleading saved state or bind the editor to the failed destination. -## Web SDK and Distribution +## HTML Import and Code-to-Design +- HTML import accepts complete documents as well as fragments and maps the + result into editable OpenPencil nodes. +- Multi-file projects can resolve local stylesheets, images, SVG content, form + controls, and relative resource URLs. +- Nested CSS imports and `url(...)` resources are resolved through the project + resource graph instead of being limited to one inline stylesheet. +- The CSS pipeline applies its supported selector subset and cascade, including + inherited values, variables, common functions, external stylesheets, and + browser-style defaults. +- Flex, Grid, absolute positioning, media-query branches, pseudo-elements, + layered backgrounds, blend modes, borders, radii, shadows, and rich text are + mapped into editable OpenPencil structures where a faithful representation is + available. +- ZIP project import reads nested paths and Unicode filenames without requiring + users to unpack the project first. +- ZIP import rejects path traversal, symbolic-link entries, encrypted or + unsupported compression modes, and packages that exceed bounded resource + limits. +- HTML and CSS decoding recognizes common byte-order marks, charset + declarations, and non-UTF-8 text encodings. +- Desktop can open or drop HTML projects through a background import session, + while the web host accepts supported file, directory, paste, and ZIP flows. +- CLI and MCP routes support HTML import and browser-snapshot conversion for + automation workflows. Remote fetches retain bounded reads and SSRF + protections. + +## Editing and Rendering + +- Component swaps, masks, layer/fill compositing, image tile scale, and page + background color are configurable instead of being import-only metadata. +- Fill-rule editing, per-corner radii, layer blur, and background blur now + reach the shared scene and paint paths. +- Missing-font prompts and font-management surfaces are available across native + and web hosts, with imported fonts invalidating affected layout scenes. +- Native user fonts are persisted and rediscovered at startup; web user fonts + are restored into the browser renderer before affected scenes are rebuilt. +- The missing-font dialog and Settings > Fonts share the same font inventory. + Users can import a source font or replace missing families across the + document with case-insensitive matching. +- Font replacement is undoable, and importing or restoring a font invalidates + text measurement and CanvasKit family caches so the canvas updates without a + restart. +- Image decoding moves off interactive paint paths where possible, with + placeholders and negative caching preventing repeated stalls for slow or + invalid assets. +- Headless screenshot and export paths still perform the synchronous decode + work needed to produce a complete deterministic result. +- Text baselines, per-corner fill geometry, even-odd shapes, image crop + transforms, and layered compositing are more consistent across canvas, + screenshot, and export rendering. +- Property-panel inputs, popovers, hover states, and CJK-aware control widths + receive additional interaction and layout fixes. + +## Web Runtime and SDK + +- Web Figma conversion uses a short-lived Worker with a separate WASM instance + and IndexedDB-backed temporary staging. +- The worker stages the generated canonical JSON, terminates after conversion, + and allows the worker's conversion-only WASM memory to be released before the + main editor installs the result. +- The main editor still reads and eagerly installs the complete canonical + document; this is not IndexedDB-backed page lazy loading. +- If Worker creation, CSP rules, browser storage, or quota prevents the staging + path, import falls back to the compatible main-thread conversion path. +- Web saves are queued and coalesced so stale work cannot overwrite a newer + document generation. +- Page fitting, masks, blend and compositing data, image tiling, page + backgrounds, and editor metadata round-trip through the web host. +- Generated TypeScript schema bindings keep the new properties optional for + v0.8.2 SDK consumers that receive older objects without those properties. - `@zseven-w/op-web-sdk`, `@zseven-w/op-web-sdk-react`, and - `@zseven-w/op-web-sdk-vue` are synchronized at `0.8.2` and published under - the npm `next` tag. -- Desktop installers and standalone `op` CLI archives are built for macOS, - Windows, and Linux. -- Platform-specific VS Code extension packages are attached to the prerelease - and published through Open VSX. -- The Rust web host is published as + `@zseven-w/op-web-sdk-vue` are synchronized at `0.8.2`. +- The tag workflow is configured to publish SDK packages under the npm `next` + tag and attach the matching package tarballs to the GitHub prerelease. +- The public web SDK remains a read-only viewer surface. + +## VS Code and Automation + +- The VS Code extension registers custom editors for `.op` and `.fig` files and + embeds OpenPencil inside the editor area rather than opening a separate + browser window. +- Each managed editor session is backed by the matching local daemon and Rust + web assets, with parent-process and stale-session cleanup. +- Offline `.fig` conversion is routed through the managed daemon and writes a + sibling `.op`; the source `.fig` file is never rewritten. +- VS Code's implicit sibling save does not currently show the desktop + replace/copy/cancel prompt or select a numbered copy when that `.op` already + exists. +- VS Code Save, Save As, Revert, backup and hot-exit recovery, undo, redo, and + keyboard focus are relayed to the active OpenPencil document. +- MCP routing follows the active custom editor and can keep the most recently + active document reachable while the MCP view owns focus. +- Extension commands cover OpenPencil MCP configuration, bundled Skill + installation and removal, and React or Vue code generation. +- Untrusted workspaces receive a restricted placeholder instead of starting the + native daemon or exposing editable document capabilities. +- Platform-specific VSIX packages bundle the correct daemon architecture and + web assets for each supported target. +- MCP document updates preserve responsive sizing keywords, and HTML/snapshot + import routes use the shared conversion and safety limits. + +## Desktop and Platform Reliability + +- Windows desktop startup falls back safely when the preferred native OpenGL + configuration cannot be wrapped by the renderer. +- Image search, image generation, Figma conversion, HTML conversion, and save + sessions use bounded or cancellable background work instead of extending the + input event path. +- Native and web page switches share fit-and-center behavior while preserving + the viewport when the current page is selected again. +- OpenPencil account sign-in entry points are temporarily hidden for this + prerelease and are planned to return in a later version. + +## Release Artifacts and Distribution + +- After the `v0.8.2` tag workflow completes successfully, it will build native + desktop installers and standalone `op` CLI archives for macOS, Windows, and + Linux. +- The workflow will attach platform-specific VS Code extension packages to the + GitHub prerelease and publish them through Open VSX. +- It will publish the Rust web host as `ghcr.io/zseven-w/openpencil-web:v0.8.2`. -- Homebrew and Scoop manifests are updated after the GitHub prerelease is - published. +- It will publish web SDK packages under the npm `next` tag and attach matching + package tarballs to the prerelease. +- Post-release jobs are configured to update Homebrew and Scoop manifests after + the GitHub prerelease is available. + +## Compatibility Notes and Current Limitations + +- `v0.8.2` is a prerelease and uses `.op` format marker `1.2`. +- New schema properties and generated TypeScript fields are optional, allowing + v0.8.2 to read older documents and object literals that omit them. +- Known legacy formats can be repaired, but future incompatible format majors + are rejected instead of rewritten. +- Active-page scenes reduce renderer memory; they do not remove non-active page + data from the canonical document. +- Web Figma staging reduces the overlap between conversion-only allocations and + the installed document in the main WASM runtime. Total browser-process peak + memory still depends on the document, Worker, storage implementation, and + browser, and the complete canonical document still enters the main runtime. +- Account sign-in is intentionally unavailable in this prerelease. +- The public web SDK remains read-only. +- The retired TypeScript application workspace is not part of this release. + +## Acknowledgements + +Thanks to the upstream maintainers behind the third-party forks documented in +the [README](https://github.com/ZSeven-W/openpencil#forked-third-party-libraries).