docs(release): expand v0.8.2 notes
This commit is contained in:
Kayshen-X
parent
fe90dc1397
commit
5c8a4163c2
|
|
@ -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).
|
||||
|
|
|
|||
Loading…
Reference in a new issue