Skip to content

Latest commit

 

History

History
331 lines (279 loc) · 19.8 KB

sharing.md

File metadata and controls

331 lines (279 loc) · 19.8 KB

Sharing contract

Documentation

Blind sharing uses encrypted, immutable links. Links expire after seven days by default; --ttl can set another lifetime or 0 for no time expiry. Every Mesh remains owned by its source path on the host.

Link forms

http://host/s/<6-char-code>
http://host/i/<6-char-code>.png

The viewer URL restores an interactive scene. The image URL performs a fresh offscreen render and returns image/png. Both derive from the same scene snapshot.

Link previews

Viewer HTML includes a scene title, bounded plain-text description, and Open Graph and Twitter Card metadata before JavaScript runs. The preview image uses the existing PNG URL; serving the HTML does not render an image or fetch resource contents. Collections advertise the combined image, while ?scene=ID selects the child's title and image. Invalid or expired links retain their HTTP error status and do not advertise a successful scene preview.

Preview URLs prefer the server's configured public origin (blind init --host) and include its base path. Viewer builds use relative asset URLs so browser exports remain inside that mount. Without a configured origin, they follow the existing Host/forwarded-host and forwarded-proto deployment contract; reverse proxies must set these headers from trusted routing configuration. The caller's Origin header, owner credentials, and viewer-only query options are not copied into metadata. Descriptions include only the public title and resource counts, not source paths or attribution. Titles are HTML-escaped, whitespace-normalized and bounded without splitting Unicode characters.

Updating metadata takes effect when the updated server binary is deployed. Messaging clients may cache existing cards; their refresh behavior and image fetch timing are outside Blind's control.

Descriptor

The encrypted descriptor contains:

  • Schema version 8, title, and creation time.
  • Canonical source path, format, byte size, and SHA-256 revision for every Mesh.
  • Registered source ID, hostname, OS user and display name (absent in some earlier local scenes).
  • Visibility, selected Mesh, color, and opacity.
  • An optional label per Mesh: {"text":"供体 A","anchor":[0,1,2]}. Text is limited to 120 characters; the optional anchor is a finite world-space point. Omitting it attaches the label to the Mesh bounds center.
  • Optional labels spanning multiple Meshes: {"text":"参考牙","meshes":[0,1]}. Mesh indices are zero-based in the descriptor and must contain at least two unique, valid members.
  • Camera position, target, up vector, field of view, zoom, projection, and orthographic height.
  • Viewport mode and, for boards, center and positive CSS-pixels-per-scene-unit scale.
  • Captured frame dimensions.
  • Surface mode, axes, and gray background mode.
  • Scene entities with a renderer type, source reference, editable label, visibility, opacity, position, size, preferred CSS-pixel panel_height, world/panel placement and component state.
  • For plugin entities, an immutable binding with plugin ID, component name, browser snapshot revision, capabilities and allowed frame origins.
  • Screen strokes with a required stable ID of 1 to 128 ASCII letters, digits, underscores or hyphens, color, capture aspect ratio, and bounded normalized points. A scene permits 64 strokes, 512 points per stroke, and 4,096 points in total.

The registry payload never contains a PAT or Mesh bytes. XChaCha20-Poly1305 encrypts and authenticates the compressed descriptor before SQLite receives it. Browser HTML lives separately in the registry's content-addressed snapshot table. Scenes reference it by revision; native plugin programs and private settings are not stored in either public scene metadata or browser snapshots.

Public and owner capabilities

The public scene code can read the exact source revisions and create another public snapshot with a changed camera or style. Public scene responses expose file names and source host/user attribution, but not absolute paths or SSH/API credentials.

An independent six-character owner secret is placed in the URL fragment of owner_url. The browser stores it only for the current session and removes it from the visible URL. Public links copied from the share sheet never contain this capability. It authorizes the Complete information option, which copies canonical source paths plus the view and image links.

Exact restore

New scenes frame visible world entities after loading; fixed panels are excluded. Spatial camera pose or board center/scale in a captured scene restore without running Fit again. Captured vertical framing remains stable across aspect ratios, while a different device may reveal more or less content horizontally. PNG export uses the same viewport and fixed-panel layout, waits for native/plugin readiness, and rejects operation mutations in export mode. Preferred pane heights are stored independently of world sizes; receiving viewports clamp actual heights without changing the preference. Missing/null heights use automatic allocation.

Screen markup is tied to that exact camera framing rather than Mesh geometry. It can cross empty space and remaps across viewport aspect ratios. The first rotate, pan, zoom, Fit, canonical-view, projection, content-scroll, content-zoom, layer or reading-window change hides all screen marks in that browser session; reloading the immutable link restores the snapshot.

Surface marks are stored in state.annotations, separately from screen strokes. Each entry has an id, zero-based mesh, source revision, kind (point or line), label, color, visible, closed, frozen 3D points, parallel surface normals, and ordered controls indexing the samples. Coordinates retain f64 round-trip precision. A scene permits 64 marks and 16,384 samples, with at most 4,096 samples per mark. Invalid indices, revisions, duplicate IDs, non-finite coordinates, invalid normals and incomplete lines are rejected before updating. The reshare body is limited to 8 MiB.

Surface marks survive camera changes and reshares without recomputing their geometry. Their source Mesh is kept at Raw quality. Marks are hidden with the Mesh and occluded by geometry; PNG exports use the same stored samples. Editing handles and names are editor UI and are not included in PNGs. Saved states without annotations load an empty annotation list. As with all scene edits, sharing creates a new immutable snapshot and leaves the old URL unchanged.

Native document reading and content marks live in each entity's state, not state.annotations or state.strokes. Reading records source SHA-256 identity, semantic target, character offset or normalized source coordinates, and the viewport attachment when needed. State also records selection, presentation, image/diagram zoom, JSON expansion and semantic graph layer. Marks contain ID, label, color, point/line kind and source anchors. One state object is shared between spatial and expanded reading and travels with the entity in reshares. Mismatched source identities are never approximately projected onto new content. The existing 64 KiB per-entity state limit applies. Invalid native state is rejected before a reshare mutates the scene; mark edits that exceed the limit leave the last valid state intact. Sources are not edited.

A read-only section is stored in state.section. It binds the plane to a Mesh entity and its source revision, and records the selected Mesh targets, plane origin and axes, slider offset, plot pan and zoom, window size, and up to two contour measurements. All visible triangle Meshes are selected when a new section is drawn; the viewer can then narrow that set. No source Mesh is edited.

Mesh labels stay attached as the camera changes. The interactive viewer projects their anchors into screen space and lays out readable text with a leader and attachment dot. Hidden Meshes and anchors outside the camera view hide their labels. Label placement adapts to the viewport and available space; text and world-space anchors are preserved in registry scene records. Labels spanning multiple Meshes draw a low-obstruction corner frame around the visible members. Their label is selectable and fits the camera to the group. Individual labels remain visible and participate in the same collision avoidance. Image links include visible Mesh and group labels. Scenes using entities or a section use Viewer export, which also includes the section window. Viewer export requires Chrome/Chromium on the Server.

For API clients, scene creation accepts an optional labels array parallel to paths, containing label objects or null. Scene/share Mesh entries expose a label field. In a share update, omit label to preserve it, send a label object to replace it, or send null to remove it. Editing and sharing creates a new snapshot; the original link is unchanged. Scene creation also accepts label_groups, an array of {text, meshes} objects. The CLI exposes both cases through one repeatable option: --label '1=牙冠' for one Mesh and --label '1,2=参考牙' for a group.

For large resource sets, blind share --config FILE accepts a single-scene manifest with resources, or a collection with independent scenes. Resources inside each scene become entities; nested collections are unsupported. The single-scene input has this strict schema:

{
  "title": "optional scene title",
  "resources": [
    { "path": "required/path.ply", "label": "optional per-Mesh label", "visible": false }
  ],
  "groups": [
    { "label": "group label", "members": [1, 2] }
  ]
}

resources is required and non-empty. groups is optional; unlike the encrypted descriptor, its members are 1-based to match CLI indices. Relative paths resolve from the config file directory. Unknown fields are errors.

visible is an optional boolean on geometry and surface resources; omission means true. Each instance retains its own initial visibility, including repeated sources and resources in Collection children. Advanced/plugin manifests support the same field on geometry resources and all components, but reject it on download-only attachments. Hidden sources are still observed and registered: their source/revision metadata and capability endpoints remain complete, and normal revision checks and revocation still apply. Visibility does not change source identity, registration ownership, or scene schema 8.

Geometry resources accept quality: "raw"|"lod" independently, including repeated references to the same source and each Collection child's resources. Omission retains LOD. LOD is a derived approximation generated when requested, not exact source geometry; each LOD-selected geometry entity produces a LOD_SELECTED warning in the share result and CLI stderr. Collection warnings remain per child. Native documents, images and plugin surfaces have no geometry quality and reject this field. Raw uses original geometry for initial viewing and PNG export without invoking derived LOD generation. Selection changes neither source bytes nor revision validation. Informational LOD_SELECTED warnings alone do not make a result partial; unavailable resources still do. Resharing after a quality change refreshes these selection warnings for the new snapshot; the original link and its quality/warnings remain unchanged.

Scene collections

A collection shares 2 to 16 independent scenes under one short link. Each scene has its own components, focused component, camera, reading, selection, rendering, visibility and annotations. By default, at most two scenes appear side by side, each with at least a 480 × 360 px viewport. Narrower windows show the active scene alone. For three or more scenes, a compact scene bar stays above the canvas. Selecting a hidden scene replaces the focused comparison pane; the other pane stays in place. Selecting an already visible scene only focuses it. 全部平铺 opts into the full responsive grid when every scene fits; 双场景对比 returns to the two-pane view. This layout preference lasts for the current session. Each pane has a top-right expand/restore button: expand fills the viewing area with that scene; restore returns to the chosen comparison or full-grid layout. Inactive viewers stay mounted at their last size to preserve reading, camera, annotations and local undo. Single-scene links have no collection controls. Panes use 1px dividers and lightweight overlaid names. The shared bottom toolbar controls the focused scene and shares the entire collection, including parked scenes. Toolbar markup starts hidden. Only the owning single-scene or Collection controller enables it; embedded child scenes never show an independent toolbar, including before scripts run or while scene requests are pending.

{
  "kind": "collection",
  "schema_version": 1,
  "title": "Case review",
  "active_scene_id": "design",
  "scenes": [
    {"id": "design", "title": "Design", "resources": [{"path": "crown.ply"}]},
    {"id": "scan", "title": "Scan", "resources": [{"path": "scan.ply"}]}
  ]
}

Each child has either resources (with optional groups, using the single scene schema above) or one plugin uri. IDs are unique lowercase letters, digits, _, or - (up to 64 characters). Collection and child titles are 1 to 120 characters. At most 256 resources are allowed in total. active_scene_id is optional and defaults to the first child. Relative paths use the config file's directory, or the working directory with --config -. Unknown fields fail validation.

blind share --config collection.json --format json
cat collection.json | blind share --config - --format json

The JSON output has viewer_url, image_url, owner_url, active_scene_id, and a scenes array with each child's id, viewer_url, image_url, resources, and warnings. GET /api/v1/scenes/<token> returns the collection overview; ?scene=<id> returns one child in the existing scene format. GET /i/<token>.png?scene=<id> exports that child. Without scene, the image route renders every child into an edge-to-edge grid, including inactive scenes. Overlaid name chips identify panes and the focused scene. Captured collection layout determines each child viewport and the cross-scene screen-ink coordinates. Collection-wide screen ink is available only when all scenes are tiled. In a partial comparison or single-scene view, the brush annotates the focused scene. Existing collection ink stays parked there and returns only with the same full grid layout and scene views; it is never overlaid on a different pair of scenes. Framing changes in either the expanded or inactive child defer invalidation until split restoration or sharing. Changed split dimensions, camera or content reading windows invalidate ink and its undo/redo history. Background initial loading does not count as navigation. Expand/restore finishes the active annotation tool before hiding its toolbar. The collection:set-layout operation accepts maximized and optional allScenes (true for full tiling, false for two-pane comparison). Omitting allScenes keeps the current preference. collection:get reports this preference and each scene's actual parked state. Layout changes wait for browser sizing and native child layout settlement before returning, so ink created afterward belongs to the completed composition.

Sharing from the collection viewer posts active_scene_id and an updates object keyed by scene ID to POST /api/v1/scenes/<token>/share. Omitted child updates keep their prior state. The result is a new immutable collection link; the old link stays unchanged.

Lifecycle

  1. The registered Client submits paths or a locally resolved manifest, plus any selected browser snapshots. The Server canonicalizes and hashes sources through read-only SFTP, a same-user local registration, or its configured OSS storage.
  2. The daemon encrypts the compact descriptor and registers a random six-character public code plus an independent owner secret. It stores no Mesh copy.
  3. Viewer metadata and reshare requests verify that the registered source is still active. A Raw or cold-LOD request reads and hashes only its target Mesh. A cached LOD request checks the target's canonical path, size, and modification time instead of scanning the whole scene.
  4. A confirmed deletion, revision change or source revocation returns 410 Gone. An offline host, timeout, host-key mismatch or denied access returns 503 Service Unavailable without tombstoning the scene. Doctor retains temporarily unavailable scenes.
  5. A link expires seven days after registration by default. --ttl selects another number of days, or 0 for no time expiry. Registering an identical active scene reuses its code and does not extend that lifetime.
  6. The registry permits 10,000 active scenes and at most 12,000 total rows. Expired and invalid tombstones are pruned and SQLite reuses released pages.
  7. Restarting the server does not invalidate active links because the registry and scene key persist in the user configuration.
  8. blind doctor audits the registry, --clean-invalid removes invalid short links, and --clear-all removes every short link without stopping the server.

Plugin bindings survive reshares without consulting a current local installation. Scene and snapshot references are registered atomically. Expired, tombstoned or removed scenes release their references; snapshots are deleted after their last reference disappears. Different Clients share identical versioned browser content, while different versions remain independent. Temporary failures retain references. Maintenance also collects snapshots for collection children.

The interactive viewer reports unavailable Meshes and retains successfully loaded ones, so one failed source does not throw away a large review scene. Unknown short-code requests are rate limited per client.

Instant image rendering

The image route:

  1. Decrypts and validates the descriptor.
  2. Parses all visible PLY, STL, OBJ, and PTS sources. Vertex-only PLY uses sphere-shaded point sprites; PTS rings use one shared generated smooth interpolating tube representation in both render paths.
  3. Rebuilds the camera, shared matte material, colors, deterministic overlap bias, and axes.
  4. Renders with the host graphics adapter into an offscreen texture.
  5. Composites the captured screen strokes with anti-aliased round joins and the same display widths used by the browser.
  6. Composites numbered annotation names and Mesh/group labels using the bundled CJK font, skipping hidden marks and hidden Meshes.
  7. Encodes PNG in memory and releases request resources.

The response uses Cache-Control: no-store, max-age=0. Blind writes no rendered image to disk and bounds concurrent renders with a semaphore. Interactive WebGL and offscreen WebGPU consume the same material parameters and lighting formula, with target-specific shader adapters. Visible sources for one image request are limited to 512 MiB, 2,000,000 triangles, and 2,000,000 point-cloud points. The byte limit is checked before any visible source is read; after rendering, Blind rechecks metadata only for the visible inputs. These limits apply only to the server-side PNG renderer; the interactive browser viewer remains independent.

Agent boundary

The CLI is canonical:

blind serve
blind share crown.ply preparation.stl --format json

blind share --help describes the complete scene and collection construction contract, including examples, limits and diagnostic recovery. An Agent needs no Skill, repository checkout or direct API calls.

Registration API

See Client/Server operation for invitation onboarding, per-user authorization, address selection, and deployment. Registered scene creation uses POST /api/v1/client/scenes with its own bearer credential; the source always comes from that credential. The old PAT-protected local creation endpoint remains for compatibility. Existing descriptors without a source ID continue to refer to local server files.