openpencil/RELEASE_NOTES/v0.8.2.md

OpenPencil v0.8.2 — Whole Apps, Faithful Imports

v0.8.2 is a prerelease focused on higher-fidelity Figma and HTML imports, multi-screen AI design generation, 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 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.
• The design agent generates multi-screen apps: screen groups can run in parallel, shared navigation is unified across screens, and app-mode screen navigation is wired into the generated document.
• Panning and zooming very large documents uses layer caching and level-of-detail so gestures stay responsive instead of dropping to a few frames per second.

Figma Import Fidelity

Components, Instances, and Swaps

• 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.

Geometry, Layout, and Text

• 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.

Canvas Performance on Large Documents

• Pan and zoom on very large documents (tens of thousands of nodes viewed zoomed out) are substantially smoother. Each change below was measured against a live profiling session rather than inferred.
• The SVG path cache is budgeted by bytes instead of entry count, so a working set of many thousands of visible paths no longer re-parses its own contents every frame.
• Text below roughly three device pixels skips shaping and paints a representative bar, and leaf content below sub-pixel size skips painting entirely.
• Shadows and blurs that would render below one pixel skip their save-layers, avoiding render-pass breaks and forced command submits that were expensive on GL-backed Metal.
• Pan gestures blit a retained offscreen layer with in-place scroll strips and an approximate scaled zoom. The layer survives across gestures, and the gesture-end frame restores full quality progressively, one tile per frame.
• The event loop places periodic wait deadlines on a fixed grid so elapsed deadlines are not re-armed immediately, removing an idle timer spin.
• OP_SLOW_FRAME_LOG=1 prints frames over 32ms with blit, scroll, and build attribution for diagnosing future regressions.

.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.
• 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.
• 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.

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.

AI Design Agent

Multi-Screen App Generation

• Screen groups can run genuinely in parallel under the parallel-agents setting, with live progress, per-group replay on completion, and distinct per-group agent identities. Sequential runs announce their setting too, so the active mode is always visible.
• Multi-screen plans give each screen group its own root frame placed beside the previous one, instead of collapsing every subtask onto a single root. Plans with zero or one screen label keep the previous single-root behavior, and append mode stays single-root.
• Generated multi-screen documents carry screen markers and onTap navigation, so app-mode preview navigates between screens instead of degrading to one scrolling page. The wiring pass is deterministic, idempotent, and additive only.
• Shared navigation bars are unified across sibling screens and injected into screens whose name matches a reference tab, so a failed navigation subtask can no longer leave a screen bare. Authored navigation is never removed.
• Active tabs are retargeted per screen even when a model draws every screen's navigation identically, and push-in detail screens (those with a header back control) no longer receive an injected tab bar.
• Tab labels match brand-prefixed screen names by whole tokens, so a screen named like Wander - Trips binds its Trips tab.
• Screens the skeleton committed but never filled are detected by shape, retried through a dedicated fill budget that does not consume the general turn cap, and reported honestly in the transcript, the run summary, and an (unfilled) canvas label when they still come up empty.
• Design routing reads a canvas signal, so a continuation request in a language the ASCII keyword gate did not match still reaches the design loop when the canvas already holds a mobile-width screen. Explicit overrides still win.

Design Quality and Geometry Repair

• Geometry diagnostics detect cross-subtree text collisions, and loop completion is gated on unresolved blockers rather than reported as done with known defects outstanding.
• A fill_container card that collapsed to a sliver beside a fixed-width sibling in a horizontal rail is widened to the widest fixed reference, before the overflow clip pass rather than after it. Evenly split and deliberately mixed fixed rails are left untouched.
• Mobile content and section rails are enforced and linted, including appended subtrees and rail edge cases, and primary mobile screens are required to carry navigation.
• Badges, pills, avatars, status dots, and compact painted text capsules get the corner radii the surrounding design already establishes, and mobile-app guidance teaches that tappable CTAs carry a corner radius.
• Decorative stack layers are exempt from the empty-shell blocker, which was pushing models to stuff content into the back layers of a card deck, and a transparent text-bearing front card gains a surface fill when a painted layer bleeds through.
• Nested card roles survive cleanup, near-full-bleed orphan cards are rescued, rejected radial sections are recovered, status indicator dots are kept out of stub cleanup, and clipped child strokes in fit-content rows are padded.
• Logical text alignment values are accepted rather than rejected, and compact status geometry is stabilized.

Providers, Models, and Skills

• The Gemini CLI provider is retired. Antigravity and Grok Build are available as agent providers and as MCP CLI integrations; the Google Gemini API provider is unaffected.
• Antigravity slug model IDs are discovered correctly, and model capability tiers were updated (MiniMax M3, Claude Fable, and Kimi K3 are treated as full-tier).
• When a CLI connect or model-discovery probe times out, OpenPencil keeps the captured output instead of discarding it, recognizes authentication prompts, and shows an actionable hint — a first-run CLI blocked on browser OAuth no longer reports only a generic timeout.
• Skill prompts are no longer silently truncated: five skills that had drifted past their injection budgets were compressed, the generation budget is the intended full-tier value, and both truncation paths now warn instead of tail-cutting quietly.
• Skill names are unique across the registry, so lookup by name is no longer order-dependent. The public get_guidelines topic key is unchanged.
• Failed subtasks keep their full spec for single-shot retry, the salvage pass retries at minimal complexity instead of repeating the full ladder, rate-limit exhaustion is classified as non-retryable, rolled-back design batches are marked as errors, and screens committed before a turn cap are salvaged rather than discarded.
• Aborted design validation terminates instead of continuing to run, and the desktop design terminal preserves its progress output.

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.
• Image fills can be cropped interactively, with the crop preview and controls in the property inspector, and image upload is wired through the file menu and the fill editor.
• Container strokes paint above their children on canvas and in SVG export, matching the expected stacking instead of being covered by child content.
• Editing a property refreshes the affected scenes, so canvas output no longer lags behind inspector changes.
• The right rail is hidden when nothing is selected instead of showing an empty inspector.
• 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.
• 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.
• Windows save commits are serialized, avoiding overlapping publications on the platform where the replace step is least forgiving.
• 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.
• 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.
• The Gemini CLI agent provider and its MCP CLI integration are removed. Existing Gemini CLI connections no longer appear in Agent Settings; the Google Gemini API provider is unaffected.
• 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.