Accessible inline object placeholders: images, equations, embeds with mandatory alt text

[accesswatch]

Source

Jarte comparison research (docs/planning/jarte.md, §4 "Inline images and embedded document objects"): Jarte could insert pictures, hyperlinks, tables, page breaks, equations, and embeddable objects. QUILL has strong support for links, tables, equations (MathCAT, Explore Equation Structure), and OCR image-to-text, but the public materials emphasize image-extraction workflows over inline image insertion with an accessible object model.

Current state in QUILL

This is the highest-uncertainty item in the whole set. QUILL's document model is plain text/Markdown with invisible formatting codes; inline binary objects (images, embedded files) don't have an obvious home in that model the way headings or tables do, since Markdown image syntax (![alt](path)) already exists but there's no evidence of a broader "accessible placeholder" concept (e.g. "Page break," "Equation," "Embedded object removed for safety") for non-image embeds. This needs real architecture investigation, not just UI work, before scope can be nailed down — hence the lower confidence despite the clear accessibility upside (mandatory alt text is a genuinely high-value, screen-reader-first idea).

Proposed approach (starting point, not a committed design)

• Accessible inline placeholders read aloud/by braille as e.g. "Image: filename.png, alt text: a sunset over the lake" or "Image: filename.png, alt text MISSING" — making missing alt text impossible to miss, not just impossible to see.
• Enforce alt text at insertion time (a required field in the Insert Image flow, not an optional afterthought).
• Equations and OCR-sourced content likely already have adjacent infrastructure (MathCAT, OCR) worth reusing rather than duplicating — needs investigation before design.
• Export cleanly to DOCX/HTML/EPUB, which already have their own accessible-image conventions to map onto.

Non-goals

• Not building a general embedded-object model for arbitrary file types (e.g. spreadsheets, OLE objects) — images and equations are the concrete, valuable cases; broader embeds are explicitly out of scope until those two are solid.

Priority rationale

High impact (mandatory alt text is a real accessibility win, not just feature parity) but low confidence — this is the one item on this list that plausibly requires a document-model change, not just a new command or dialog, so it's ranked below several smaller, surer wins despite its potential value. Recommend a short spike/investigation before committing to a design.

[accesswatch]

Partial correction to my original research — the accessibility story here is further along than I said.

What already exists (I under-checked this): quill/core/glow.py (the GLOW accessibility audit/repair suite) already:

• Flags missing alt text as an audit finding ("Add concise alt text inside the image brackets", "Add alt text or alt="" for decorative images")
• Auto-fixes it ("Added empty alt attributes to img elements missing alt text")
• Can generate alt text with a cloud AI model (ai_alt_text feature, opt-in)
• Catalogs every image and its alt-text status via quill/core/link_inventory.py (ImageAltRecord, flags "(missing alt text)")

So "does QUILL have an accessible object model for image alt text" — yes, via GLOW. What GLOW doesn't do is the two things this issue is actually about:

1. Proactive enforcement at insertion time — GLOW is an audit-and-repair pass you run after content exists; there's nothing today that requires alt text when you insert an image, the way this issue proposes.
2. Inline reading experience — GLOW produces a report; it doesn't change what a screen reader announces when the caret passes an image inline in the live document ("Image: filename.png, alt text: ..." vs. "Image: filename.png, alt text MISSING").

Narrowing this issue to those two gaps (proactive insertion-time requirement + inline announcement), reusing GLOW's existing alt-text data model (ImageAltRecord) rather than inventing a new one. Equations and generic embedded objects (the other half of the original scope) stay as explicitly lower-confidence, needs-investigation territory — the alt-text half is now much better-grounded than when I filed this.