sealed-surface 0.1.0

Non-extractable data surface: tables painted as glyphs, never as DOM text
Documentation

sealed-surface

crates.io docs.rs license

A Rust library that paints tables (and, later, charts) as a bitmap of glyphs so the numbers you can see are not numbers a web scraper can collect.

Not DRM. Not OCR-proof. A phone camera still wins. The crate signs DOM scrape, copy/paste, and tooltip-JSON layers when the host obeys the contract. Sealed grids do not put values in the accessibility tree; the accessible egress is a licensed API the host already meters. Do not “fix a11y” with a hidden <table> — that hidden table is the scrape.

Zero required crates.io dependencies. Table-first (0.1). Charts are reserved.

[dependencies]
sealed-surface = "0.1"
cargo test
cargo run --example host_contract

1. The problem, in the language of a normal webpage

When you open a typical analytics UI, you see a table of prices or a chart of counts. Your eyes are looking at pixels. Your browser, however, is holding several other copies of the same facts:

Place What it is Who can read it
DOM The HTML tree: <td>49.00</td>, or a <div>, or SVG <text>49.00</text> Anyone: View Source, document.body.innerText, Python pandas.read_html, “Table to Excel” extensions
JavaScript heap The array the chart library used to draw: [{x, y: 49.00}, …] Anyone with DevTools, a userscript, or a bookmarklet
Network tab The JSON the page fetched: {"price": 49.00} Anyone who can open DevTools → Network
Clipboard What Ctrl+C copies Anyone who can select
Accessibility tree What a screen reader speaks; often the same Unicode as the DOM Assistive tech and scrapers that walk ARIA
Pixels The picture on screen Humans, screenshots, cameras, OCR, vision models

A data moat for a visual product is the decision that the pixels are the product and the other copies are leaks.

If you sell a licensed API for the real rows, the UI must not be a free back-door CSV. That is the whole game. We are not hiding a password. We are making “save this table to Excel” fail for a typical customer, so buying the API is the rational next step.

We will not stop a determined person with a phone camera and a vision model. Bloomberg does not stop that either. We will stop copy, scrape, and casual DevTools harvest.


2. Why the usual “protections” are not a moat

If you have ever seen a site that “blocks copy,” you have seen theater.

user-select: none and “disable right click”

CSS can ask the browser not to highlight text. The text is still in the DOM. A scraper does not highlight. It reads textContent. Extensions that copy tables do not care about your CSS. This is a courtesy to accidental selection, not a defense.

Blur the remaining rows in CSS

A common SaaS lure: show two clear rows, blur the rest, overlay a lock icon. If the blurred rows were sent as HTML and then styled with filter: blur(), the values are still in the tree. View Source, disable CSS, or document.querySelectorAll('td') recovers them. A blur over live data is an invitation, not a lock.

The correct lure is: the locked rows were never sent. What you paint is a placeholder (.... / LOCK) whose original scalar has already been dropped.

SVG of strings and numbers

SVG is XML. <text x="10" y="20">49.00</text> is a DOM node. It is selectable, searchable, and scrapable. Even if you draw letters as <path d="M …"> (Amazon Kindle Cloud Reader did this, with randomized glyph IDs), the paths sit in the document. Researchers rasterized those paths and matched them to a font atlas; others ran OCR on the page canvas. SVG-as-a- document is not a picture. It is data with extra syntax.

This crate may use glyph outlines internally someday. It will never attach an SVG document to the page.

Canvas fillText from a JavaScript array

HTML <canvas> is a bitmap. fillText("49.00") does not create a DOM text node. That is better than a <table>. It is not enough if the page also holds const series = [49.00, …] in JS, because the thief reads the array, not the pixels. Wrapping TradingView lightweight-charts, ECharts, or Plotly from Rust/WASM has the same leak: the series still materialize in JS.

“It’s WASM, so it’s compiled”

WebAssembly is a sandbox for code, not a vault for values. If the numbers live in WASM linear memory, a motivated intern can dump that memory. v0 of this crate therefore paints on the server (or in a native test) and sends PNG bytes. The browser receives a picture. Future WASM backends must keep scalars off the JS heap; they still will not be magically secret.


3. The threat model (what we sign, what we don’t)

Think in layers. Each layer is a different attacker, with a different cost.

Layer Attack What this crate does Residual
A. DOM scrape innerText, <td>, SVG <text>, ARIA, CSS content In Sealed mode, HostProjection contains no cell values The host app must not also dump JSON into HTML
B. Copy / Excel extensions Ctrl+C, table-to-Excel Sealed mode emits no TSV / no HTML table Screenshot still works
C. Tooltip / hit JSON GET /tooltip returns {"value":"49.00"} Tooltip is a PNG. Hits are opaque {row, col} ids A sloppy host can still add a JSON route; don’t
D. JS / WASM memory Dump the heap v0: values never go to the browser as strings A future WASM port can be dumped
E. OCR / vision Screenshot, getImageData, phone + GPT-4V Out of scope for v0 This is the honest floor
F. Licensed API Customer has a key and pulls JSON Not this crate Intended egress, metered elsewhere

We sign A–C when the host obeys the contract below. We do not sign E. If someone claims a web UI is “impossible to steal,” they are selling DRM cosplay.

The product goal is friction. A typical analyst should find copy-paste broken, View Source empty of prices, and Network filled with image/png. Then they buy the API.


4. How this crate actually does it

Defense is a sequence. Skipping a step undoes the rest.

Grid  ──LicenseLens.apply──►  ViewGrid   (unlicensed scalars are gone)
                                 │
                           TableLayout   (rectangles, not HTML)
                                 │
                    embedded 5×7 bitmap font
                                 │
                         Pixmap (RGB bytes)
                                 │
                    in-crate PNG encoder
                                 │
              ┌──────────────────┼──────────────────┐
              ▼                  ▼                  ▼
         frame PNG          tooltip PNG        HostProjection
         (always)         (pointer hit)     (empty if Sealed)

Step 1 — Drop what they should not see (LicenseLens)

Before a single pixel is drawn, LicenseLens::apply clones the grid and overwrites unlicensed cells with CellValue::Redacted. The original 49.00 is not stored next to the placeholder. There is no “hidden” field to accidentally serialize.

Tiers are product-agnostic. Hosts map their plans onto them:

AccessTier Clear data rows
Public 0 (headers still painted; every cell redacted)
Trial 2
Subscription / Pro / Enterprise / Open all rows in the grid you supplied

Open is for admin tools. Column allow-lists can redact whole columns even in sample rows.

This is the answer to CSS blur: you cannot scrape a number that left memory before paint.

Step 2 — Paint glyphs, not Unicode (font + raster)

An HTML table stores the character '4', then '9', then '.'. A sealed surface stores which pixels of a tiny 5×7 font are on. The font lives inside src/font.rs as bit patterns. It is not a webfont, not a system font, not a <span>.

Pixmap is a rectangle of RGB bytes. text() walks each character, turns bits on, and writes colors. Grid lines and hover fills are rectangles. There is no text layer.

Step 3 — Encode a PNG, not a document (raster::to_png)

PNG is a compressed picture. Opening it in DevTools shows an image. It does not show a table. The encoder is in-crate (DEFLATE + LZ77, no png or image crate) so the publish graph stays tiny and tests run anywhere.

The host should serve that buffer as Content-Type: image/png and put it in <img src="…">. Empty alt. No aria-label of the values.

Step 4 — Separate “what the human sees” from “what the host may emit”

SurfaceMode does not change the painter. Both modes rasterize glyphs.

Mode Pixels HostProjection
Sealed (default) PNG no text nodes, no clipboard
Copyable same painter TSV of the (already lensed) viewport

Admin UIs can toggle copy for operators who need to paste a run_id and sometimes a debug grid. Customer UIs must never set Copyable on analytical views. The toggle exists so we can prove, with tests, that only the leak surface changes — we did not build two widgets.

HostProjection::audit_text() concatenates everything the host is allowed to put in HTML or on the clipboard. Contract tests grep that string for fixture values like "49.00" and "ACME-SKU-1" and expect zero matches in sealed mode.

Step 5 — Tooltips are pictures too

Hover is the easiest way to undo a sealed table. If the tooltip is <div>49.00</div> or {"value":"49.00"}, you just reopened the DOM and the network tab.

FrameRequest.pointer is an (x, y) in PNG space. The crate:

  1. looks up a Hit (row/col ids, never values),
  2. paints a tiny pixmap of header: glyphs,
  3. returns tooltip_png: Option<Vec<u8>>.

The host JS must assign img.src to that PNG URL. It must never call response.text().

Step 6 — Hits are coordinates, not facts

HitMap::at(x, y) -> Option<Hit> gives row, col, row_index, col_index, kind. You can highlight a cell or ask for a tooltip PNG. You cannot learn 49.00 from the hit type. That is deliberate.


5. A map of the code

src/
  lib.rs        public API (small on purpose)
  model.rs      Grid, Column, Row, CellValue
  lens.rs       AccessTier, LicenseLens (drop scalars)
  mode.rs       Sealed | Copyable
  layout.rs     viewport clip + sticky header + HitMap (visible only)
  deflate.rs    in-crate zlib/DEFLATE (no crates.io codec)
  font.rs       5×7 bitmap
  raster.rs     Pixmap + PNG encoder
  host.rs       HostProjection (the leak surface)
  surface.rs    Surface::render  — the pipeline
  theme.rs      RGB palette
  chart.rs      reserved; returns UnsupportedLayout
  error.rs      InvalidGrid | UnsupportedLayout | Raster
tests/
  seal_contract.rs   load-bearing greps
  virtualize.rs      window clip / sticky header / metrics

Surface::render is the only function you need to understand end-to-end:

  1. viewed = lens.apply(grid) — secrets for unlicensed cells are gone.
  2. layout_visible — column widths from the viewed grid (or host override); only the viewport gets boxes. Sticky header; origin_y scrolls the body.
  3. Allocate a window-sized Pixmap (capped at MAX_PIXMAP_AXIS), paint visible cells, grid lines, optional hover fill. TableMetrics is the scrollbar query (Surface::metrics).
  4. to_png().
  5. If there is a pointer, maybe tooltip_png.
  6. Build HostProjection from mode, not from pixels.

Charts (SeriesLayout) are a reserved module so applications can depend on sealed_surface::chart now without filling the gap with ECharts. Calling render returns Error::UnsupportedLayout("series") until a timeseries layout lands on this painter.


6. Rust, for people who live on the web

You do not need to be a Rust expert to follow the crate. A few language choices are the defense.

Enums instead of “strings with meaning”

CellValue is not String plus a comment. It is:

Empty | Text | Int | Float { value, decimals } | Redacted

Redacted cannot carry a hidden number. If you want a price, you must use Float or Text. After the lens, unlicensed cells are the Redacted variant. There is no { display: "....", actual: 49.00 } to leak into JSON.

SurfaceMode and AccessTier are the same idea: invalid combinations are harder to represent. You cannot pass "sealed-ish".

Ownership: the lens does not “hide,” it replaces

LicenseLens::apply clones the grid and writes Redacted into cells. Rust makes that mutation explicit. There is no prototype chain, no Vue reactivity accidentally keeping the old object around, no Object.defineProperty trap. The viewed grid is a new value. Frame.viewed is that value. Tests call viewed.debug_values() and assert "SECRET-ROW" is absent after a trial lens.

Result instead of panic

Library code returns Result<Frame, Error>. A zero-width pixmap or a ragged grid is an error, not a crash in someone else’s server. (unwrap is reserved for tests.)

Zero dependencies, on purpose

v0 does not pull png, image, tiny-skia, wasm-bindgen, or Leptos. The PNG encoder is a few dozen lines. That is not machismo — it is so:

  • cargo test -p sealed-surface runs on a native toolchain with no browser,
  • the crate can be extracted and published without dragging a UI framework,
  • the defense is not “we used a fancy GPU library.”

WebGPU/Canvas will be optional features later, behind the same Grid → HostProjection contract.

Tests are the spec

tests/seal_contract.rs is more important than this paragraph. It:

  • greps sealed audit_text() for "49.00" and SKUs and expects none,
  • greps copyable TSV and expects them present,
  • proves set_mode flips the leak surface without a second widget,
  • proves the trial lens drops row 2 (SECRET-ROW) even if the host asked for a copyable TSV,
  • proves a tooltip is PNG bytes, not host text,
  • proves hits return indexes, not values.

If you change the painter and break a grep, you have opened a leak. That is the point of putting the greps in CI.


7. The web, for people who live in Rust

A sealed surface is only as strong as the host that embeds it. Here is the web surface in one picture:

<div class="sealed-host" data-token="…" data-mode="sealed">
  <img class="surface" alt="" src="/surface/{id}/frame.png" />
  <img class="tooltip" alt="" hidden />
</div>

That is the entire DOM for the data. Pointer JS may compute x, y from the mouse and set tooltip.src to another PNG URL. It may not parse the response as text.

DOM vs pixels (again, because this is the whole trick)

The browser’s document is a tree of nodes. Scrapers walk that tree. innerText is “give me all the Unicode in this subtree.” If your prices are not in the subtree, innerText cannot give them.

An <img> node’s content is a bitmap fetched as image/png. The Unicode inside the PNG file is a compression format, not the string "49.00". (A pathological uncompressed PNG could accidentally contain those bytes as pixel values. We do not treat PNG greps as the contract. HostProjection is the contract.)

Why not a <canvas> in v0?

Canvas is also pixels, and a fine later backend. v0 is server-rendered PNG because:

  • values never enter the browser as strings (layer D),
  • native cargo test can prove the contract without a headless Chrome,
  • the host is forced into the <img> shape, which is hard to accidentally turn back into a table.

HTTP is part of the moat

If GET /surface/1/tooltip.png?x=10&y=20 returns JSON, you lost. The Content-Type must be image/png. Clipboard TSV, if you offer it at all, must 403 when the session is sealed. An /audit dump of HostProjection is a lab tool (KINNA_ADMIN_AUDIT=1); it is a weapon if copied into production customer UI.

Accessibility is a product choice, not an accident

Screen readers read the accessibility tree, which is usually the DOM. A sealed grid therefore has nothing useful to say. That is intentional. The accessible path for real values is the licensed API (or, for admins, Copyable mode / ops chrome). Do not “fix a11y” by injecting a hidden <table>. That hidden table is the scrape.

Clipboard

The Clipboard API can write text/plain, HTML, or images. Sealed mode writes nothing. Copyable mode writes TSV (tabs and newlines), which pastes into Excel, not an HTML table that would reintroduce DOM structure if you were sloppy. Customer products should not expose that route.


8. Host contract (do not undo the crate)

The library paints. The host is the other half.

Allowed

  • <img> of the frame PNG and tooltip PNG
  • Opaque session token in a data- attribute
  • Pointer coordinates as query parameters
  • Your own chrome: nav, buttons, operator strings (run_id, listen address) in normal HTML
  • Copyable TSV for admin-only sessions

Forbidden

  • view! { {price} } / React {row.price} / any template interpolation of a cell
  • Tooltip or hit JSON that includes values
  • Hydrating a WASM table of strings “for SEO”
  • CSS blur over real rows
  • Shipping the same rows as JSON to a SPA store “and also” painting a PNG
  • Putting grain IDs, SKUs, or prices in alt, title, or aria-label

If you do those, this crate cannot save you. The tests in this package will still pass. Your page will still leak. That is why kinna-admin’s tests/html_seal.rs greps the HTML document, not only HostProjection.


9. Using the library

use sealed_surface::{
    AccessTier, CellValue, Column, FrameRequest, Grid, LicenseLens, Row, Surface,
    SurfaceMode, Viewport,
};

let grid = Grid::try_new(
    vec![Column::new(0, "sku"), Column::new(1, "price")],
    vec![Row::new(
        0,
        vec![CellValue::text("ACME-SKU-1"), CellValue::float(49.0, 2)],
    )],
)?;

let mut surface = Surface::new(
    SurfaceMode::Sealed,
    LicenseLens::from_tier(AccessTier::Trial),
);
let frame = surface.render(&grid, &FrameRequest::full(Viewport::window(640, 240)))?;

assert!(frame.host.clipboard.is_none());
assert!(!frame.host.audit_text().contains("49.00"));
assert!(frame.png.starts_with(b"\x89PNG"));
let _scroll = surface.metrics(&grid); // content_width/height for host scrollbars

surface.set_mode(SurfaceMode::Copyable);
let copyable = surface.render(&grid, &FrameRequest::full(Viewport::default()))?;
assert!(copyable.host.audit_text().contains("ACME-SKU-1"));
# Ok::<(), sealed_surface::Error>(())

Serve frame.png as image/png. For hover, pass FrameRequest { pointer: Some(Pointer { x, y }), .. } and serve tooltip_png the same way.


10. What this is not

  • Not DRM. Not watermark-as-proof-in-court (later, maybe, as attribution).
  • Not OCR-proof, screenshot-proof, or camera-proof.
  • Not a TradingView clone. Do not wrap lightweight-charts “until charts land.”
  • Not an HTML table with extra CSS.
  • Not a substitute for API metering, auth, or legal terms. Those are other layers. This crate is the visual layer.

11. Roadmap (crate only)

Slice Intent
0.1 (now) Virtualized table, DEFLATE PNG, metrics, host examples. See ROADMAP.md.
0.2 Timeseries on this painter (crosshair as glyphs, no JS series)
0.3 Scatter, treemap
0.4 Optional web / wgpu blit; values stay off the JS heap
0.5 Optional glyph shuffle + tenant watermark (attribution, not OCR-proof)
0.6 Server tiles for 100k-row grids

Publish to crates.io when the greps stay brutal and the table feels like a real grid (ROADMAP.md §6). The name sealed-surface is product-agnostic on purpose.

Normative decision record in the Kinna monorepo: docs/feats_and_lessons/adr_sealed_surface.md.