pretext-layout

Integrate, debug, or prototype @chenglou/pretext for browser-based multiline text measurement and manual line layout. Use when replacing DOM height probes, b...

Security Scan

The skill is internally consistent with its stated purpose (browser-side multiline text measurement), requests no credentials, contains only documentation plus a harmless scaffold script, and does not attempt unexpected access or installs.

Purpose & Capability

Name and description match the contents: guidance about using @chenglou/pretext in browser contexts, usage patterns, caveats, and a small demo scaffold. The declared required binaries (bash, node, npm, python3) are reasonable for running demos or developer tooling and do not conflict with the stated purpose.

Instruction Scope

SKILL.md instructions focus on preparing and measuring text in browser runtimes and explicitly warn about server-side constraints. They do not instruct reading unrelated files, exporting secrets, or calling external endpoints. The only filesystem action is the scaffold script (writes index.html and demo.mjs) which is aligned with the declared 'scripts' usage.

Install Mechanism

There is no install spec (instruction-only), so nothing is downloaded or executed by the platform. The included scaffold references a typical /node_modules path for @chenglou/pretext; the skill does not automatically fetch remote archives or run installers, which keeps installation risk low.

Credentials

The skill requests no environment variables, secrets, or config paths. The absence of credentials is proportional to a library-integration helper. The only operational requirements are developer binaries (node/npm/python3) needed to run the scaffold/demo locally.

Persistence & Privilege

The skill is not always-on, does not request elevated persistence, and does not modify other skills or system-wide settings. It is user-invocable and can be invoked autonomously per platform defaults, which is expected for a utility skill.

Assessment

This skill appears to be a documentation + demo scaffold for the @chenglou/pretext library and is coherent with that goal. Before installing or using it: (1) confirm you actually want a browser-based integration (it intentionally does not promise Node-only support), (2) if you run the scaffold you'll need to install @chenglou/pretext via npm and serve the generated files from a dev server, (3) review the third-party package (@chenglou/pretext) from npm if you care about supply-chain risk, and (4) the included Python script only writes two local files (index.html and demo.mjs) — run it in a disposable directory if you want to be cautious. There are no credential requests or hidden network calls in the provided files.

Overview

Use Pretext to measure multiline text in browser environments without paying repeated DOM reflow costs in the hot path. Prefer it when text width changes often and you need stable height or per-line geometry from cached measurements.

Workflow

1. Confirm the runtime first.
   • Treat Pretext as browser-first.
   • If the task is pure Node or CLI with no OffscreenCanvas and no document, do not promise direct runtime support.
2. Match the API to the job.
   • Use prepare() plus layout() for height and line-count measurement.
   • Use prepareWithSegments() plus layoutWithLines(), walkLineRanges(), or layoutNextLine() for custom rendering.
3. Sync layout inputs with real styles.
   • Read font and line-height from the target element or design token source.
   • Wait for document.fonts.ready before trusting measurements when web fonts are involved.
4. Cache aggressively.
   • Prepare once per (text, font, whiteSpace, locale) input.
   • Reuse the prepared handle across width changes.
5. Verify against the real UI when accuracy matters.
   • Compare a few representative strings against live DOM heights.
   • Include multilingual, emoji, and narrow-width cases if the feature depends on them.

Decision Guide

• Reach for prepare() plus layout() when the user needs block height, resize performance, virtualization, scroll anchoring, or pre-measuring text before render.
• Reach for prepareWithSegments() plus rich line APIs when the user needs custom line drawing, canvas text, SVG text, shrink-wrap width discovery, or variable line widths.
• Reach for ordinary DOM measurement instead when the task depends on CSS behaviors Pretext does not aim to cover fully.

Core Rules

• Do not claim server-side support unless the target environment actually provides a compatible canvas context.
• Keep font and lineHeight aligned with the real UI; measurement errors usually come from mismatched inputs, not from the layout call itself.
• Avoid system-ui for accuracy-sensitive flows on macOS; prefer named fonts.
• Treat prepare() as the expensive step and layout() as the hot path.
• When working with textarea-like content, pass { whiteSpace: 'pre-wrap' } explicitly.

Implementation Checklist

• Identify the exact text source, target width source, font source, and line-height source.
• Decide whether the feature only needs height or also needs per-line data.
• Cache prepared handles instead of calling prepare() on every resize.
• Add a small verification path that compares Pretext output with live DOM for representative samples.
• Document any unsupported CSS or runtime assumptions close to the integration point.

Scripts

• Run scripts/scaffold_browser_demo.py --out <dir> when you need a minimal browser starter wired to @chenglou/pretext.
• Use the scaffold as a disposable starting point; adapt font, line-height, white-space mode, and UI markup to the real project after generation.

References

• Read references/browser-integration.md for the common browser setup pattern and a reusable measurement loop.
• Read references/usage-patterns.md when choosing between the simple and rich APIs.
• Read references/caveats.md before answering questions about accuracy, fonts, white-space, emoji, bidi behavior, or non-browser runtimes.
• Read references/project-examples.md for portable integration patterns you can adapt to any browser-based app or AI CLI workspace.