timeglance 1.0.0__tar.gz

timeglance-1.0.0/.dockerignore

@@ -0,0 +1,9 @@
+.git/
+.venv/
+**/__pycache__/
+**/*.pyc
+**/out/
+state/
+docs/
+*.md
+!README.md

timeglance-1.0.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  # Maintain dependencies for Python packages
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

timeglance-1.0.0/.github/workflows/bandit.yaml

@@ -0,0 +1,22 @@
+name: bandit
+
+on:
+  pull_request:
+    branches: ["main*"]
+  push:
+    branches: ["main"]
+
+jobs:
+  bandit:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - name: Install uv and sync dependencies
+        run: |
+          pip install uv
+          uv sync --frozen
+      - name: Run bandit
+        run: uv run bandit -r src/timeglance -c pyproject.toml

timeglance-1.0.0/.github/workflows/pip-audit.yaml

@@ -0,0 +1,22 @@
+name: pip-audit
+
+on:
+  pull_request:
+    branches: ["main*"]
+  push:
+    branches: ["main"]
+
+jobs:
+  pip-audit:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - name: Install uv and sync dependencies
+        run: |
+          pip install uv
+          uv sync --frozen
+      - name: Run pip-audit
+        run: uv run pip-audit

timeglance-1.0.0/.github/workflows/pre-commit.yaml

@@ -0,0 +1,25 @@
+name: pre-commit
+
+on:
+  pull_request:
+    branches: ["main*"]
+  workflow_call:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - name: Get python version
+        run: echo "PY=$(python -VV | sha256sum | cut -d' ' -f1)" >> $GITHUB_ENV
+      - uses: actions/cache@v6
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit|${{ env.PY }}|${{ hashFiles('.pre-commit-config.yaml') }}
+      - name: Install pre-commit
+        run: pip install pre-commit
+      - name: Run pre-commit
+        run: pre-commit run --all-files --show-diff-on-failure --color=always

timeglance-1.0.0/.github/workflows/release.yaml

@@ -0,0 +1,68 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+# semantic-release pushes its `RELEASE: {version}` commit with a PAT, which re-triggers this
+# workflow. That commit has nothing to test or release, so skip every job on it (the alternative,
+# `[skip ci]` in the commit message, works too but is less explicit). On the RELEASE commit all
+# jobs skip; `release` needs the skipped jobs, so it skips with them.
+jobs:
+  pre-commit:
+    if: ${{ !startsWith(github.event.head_commit.message, 'RELEASE:') }}
+    uses: ./.github/workflows/pre-commit.yaml
+  tests:
+    if: ${{ !startsWith(github.event.head_commit.message, 'RELEASE:') }}
+    uses: ./.github/workflows/tests.yaml
+  release:
+    name: Release
+    needs: [pre-commit, tests] # a broken build never reaches the release step
+    if: ${{ !startsWith(github.event.head_commit.message, 'RELEASE:') }}
+    runs-on: ubuntu-24.04
+    concurrency:
+      group: ${{ github.workflow }}-release-${{ github.ref_name }}
+      cancel-in-progress: false
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
+      - name: Python Semantic Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v10
+        with:
+          github_token: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
+
+  # Publish to PyPI only when a release was actually cut (gated on the action's structured
+  # `released` output, never log-grepping). It runs in the `pypi` environment, so the OIDC
+  # token - and thus publishing rights - is scoped to this job rather than the whole workflow.
+  # Trusted publishing means no API token, and gh-action-pypi-publish attaches sigstore
+  # attestations by default. Dormant until the first release (1.0.0) is cut.
+  publish:
+    name: Publish to PyPI
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/timeglance
+    permissions:
+      id-token: write
+      contents: read # checkout needs read access while the repo is private
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          ref: ${{ needs.release.outputs.version }} # the tag semantic-release just pushed
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - name: Build distributions
+        run: pip install uv && uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

timeglance-1.0.0/.github/workflows/tests.yaml

@@ -0,0 +1,27 @@
+name: tests
+
+on:
+  pull_request:
+    branches: ["main*"]
+  workflow_call:
+
+jobs:
+  tests:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - name: Install system libraries for WeasyPrint & CairoSVG
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0 \
+            libffi8 shared-mime-info fonts-dejavu-core fonts-noto-core
+      - name: Install uv and sync dependencies
+        run: |
+          pip install uv
+          uv sync --frozen
+      - name: Run tests
+        run: uv run pytest

timeglance-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.pyc
+.venv/
+.ruff_cache/
+.pytest_cache/
+dist/
+weekly/out/
+year/out/
+state/
+
+# Private working configs; scaffold them with `timeglance-init`. The year config can hold
+# calendar share links / secrets; the weekly config is your personal schedule.
+weekly/config.yaml
+year/config.yaml
+
+# Backups written before a "reset to template" (config.yaml.<stamp>.bak etc.)
+*.yaml.*.bak

timeglance-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: v3.3.3
+    hooks:
+      - id: prettier
+        types_or: [markdown]
+        # CHANGELOG.md is generated by semantic-release; prettier would reformat it and fail
+        # the release commit's CI. `exclude` (not .prettierignore) also avoids prettier's
+        # "No matching files" error when a commit touches only the changelog.
+        exclude: ^CHANGELOG\.md$

timeglance-1.0.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+<!-- version list -->
+
+## v1.0.0 (2026-10-03)
+
+- Initial Release

timeglance-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+Patches welcome! Open an issue for bugs and ideas, or a PR for changes.
+
+## Setup
+
+```sh
+uv sync
+pre-commit install
+```
+
+Hooks: **ruff** (lint + format) for Python, **prettier** for Markdown.
+
+The code lives under `src/timeglance/` (`common`, `year`, `weekly` subpackages); packaged assets (web UI, Jinja
+templates, the `config.yaml.in` files) ship inside it. Working data - each tool's `config.yaml` and `out/`, plus
+shared `state/` - resolves from the current working directory (override with `TIMEGLANCE_HOME`).
+
+## Before you push
+
+`uv run pytest` and `pre-commit run --all-files` should pass. Commit messages follow
+[Conventional Commits](https://www.conventionalcommits.org) (`feat:`, `fix:`, `docs:`, …) - they drive the automated
+version bumps and changelog.
+
+## Continuous integration
+
+Every pull request runs **pre-commit** (ruff + prettier) and the **pytest** suite (with the WeasyPrint/CairoSVG
+system libraries installed), plus **pip-audit** (dependency CVEs) and **bandit** (security lint). Pushes to `main`
+run those again and then the release job.
+
+## Releasing
+
+Versioning is automated with [python-semantic-release](https://python-semantic-release.readthedocs.io), driven by
+[Conventional Commits](https://www.conventionalcommits.org):
+
+- `feat: …` → minor bump, `fix: …` → patch bump, breaking change (`feat!: …` or a `BREAKING CHANGE:` footer) →
+  major bump; `docs:` / `refactor:` / `perf:` show up in the changelog.
+- An optional scope narrows the area, e.g. `feat(weekly): …` or `fix(year): …`.
+
+On every push to `main`, CI runs semantic-release. When the new commits warrant a bump (per the rules above) it
+raises the version in `pyproject.toml` (and `src/timeglance/__init__.py:__version__`), updates the changelog, tags,
+and cuts a GitHub Release; otherwise it does nothing. This needs a `SEMANTIC_RELEASE_TOKEN` secret (a PAT with
+`contents: write`). That same version bump then publishes the build to PyPI via
+[trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC, no API token) from the `pypi` environment.

timeglance-1.0.0/Dockerfile

@@ -0,0 +1,29 @@
+# timeglance: renders weekly sheets (WeasyPrint) and the year planner (CairoSVG).
+FROM python:3.13-slim-bookworm
+
+ENV PYTHONUNBUFFERED=1 \
+    UV_LINK_MODE=copy \
+    UV_COMPILE_BYTECODE=1 \
+    PATH="/app/.venv/bin:$PATH"
+
+# Native libraries for WeasyPrint + CairoSVG, plus the fonts the templates reference.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0 \
+      libffi8 shared-mime-info fonts-dejavu-core fonts-noto-core \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:0.8.2 /uv /uvx /bin/
+
+WORKDIR /app
+
+# Install dependencies first (cached from the lockfile), then the project itself.
+COPY pyproject.toml uv.lock README.md ./
+RUN uv sync --frozen --no-dev --no-install-project
+COPY src ./src
+RUN uv sync --frozen --no-dev
+
+EXPOSE 8753
+
+# Default: the timeglance control panel (both tools). Override for a one-shot render, e.g.
+#   docker compose run --rm timeglance timeglance-weekly
+CMD ["timeglance", "--host", "0.0.0.0"]

timeglance-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny W. Adair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

timeglance-1.0.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: timeglance
+Version: 1.0.0
+Summary: Printable weekly routine sheets and a year-at-a-glance planner / desktop wallpaper.
+Project-URL: Homepage, https://github.com/dannyadair/timeglance
+Project-URL: Repository, https://github.com/dannyadair/timeglance
+Project-URL: Issues, https://github.com/dannyadair/timeglance/issues
+Author-email: "Danny W. Adair" <danny.adair@unfold.nz>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calendar,ical,kde,pdf,planner,plasma,schedule,svg,wallpaper,yaml
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.13
+Requires-Dist: cairosvg>=2.7.1
+Requires-Dist: holidays>=0.105
+Requires-Dist: icalendar>=7.3.0
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pypdfium2>=4.30.0
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: recurring-ical-events>=3.8.2
+Requires-Dist: weasyprint>=62.3
+Description-Content-Type: text/markdown
+
+# timeglance
+
+[![Python](https://img.shields.io/python/required-version-toml?color=blue&tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fdannyadair%2Ftimeglance%2Fmain%2Fpyproject.toml)](https://github.com/dannyadair/timeglance/blob/main/pyproject.toml)
+[![tests](https://github.com/dannyadair/timeglance/actions/workflows/tests.yaml/badge.svg)](https://github.com/dannyadair/timeglance/actions/workflows/tests.yaml)
+[![pre-commit](https://img.shields.io/github/actions/workflow/status/dannyadair/timeglance/pre-commit.yaml?label=pre-commit&logo=pre-commit&logoColor=white)](https://github.com/dannyadair/timeglance/actions/workflows/pre-commit.yaml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![pip-audit](https://img.shields.io/github/actions/workflow/status/dannyadair/timeglance/pip-audit.yaml?label=pip-audit&logo=python)](https://github.com/dannyadair/timeglance/actions/workflows/pip-audit.yaml)
+[![bandit](https://img.shields.io/github/actions/workflow/status/dannyadair/timeglance/bandit.yaml?label=bandit&logo=python)](https://github.com/dannyadair/timeglance/actions/workflows/bandit.yaml)
+[![Last commit](https://img.shields.io/github/last-commit/dannyadair/timeglance?color=lightgrey)](https://github.com/dannyadair/timeglance/commits/main)
+[![License](https://img.shields.io/github/license/dannyadair/timeglance?color=lightgrey)](https://github.com/dannyadair/timeglance/blob/main/LICENSE)
+
+<!-- Add once published to PyPI (and if you wire up these services), matching pdfbaker:
+[![PyPI version](https://img.shields.io/pypi/v/timeglance?color=blue)](https://pypi.org/project/timeglance/)
+[![Downloads](https://img.shields.io/pypi/dw/timeglance?color=blue)](https://pypistats.org/packages/timeglance)
+[![sigstore](https://img.shields.io/badge/sigstore-signed-blue)](https://github.com/dannyadair/timeglance/releases)
+[![codecov](https://img.shields.io/codecov/c/github/dannyadair/timeglance)](https://codecov.io/gh/dannyadair/timeglance)
+[![OSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/dannyadair/timeglance?label=OSSF%20Scorecard)](https://scorecard.dev/viewer/?uri=github.com/dannyadair/timeglance)
+-->
+
+Config-driven time planning at a glance - one web UI controls two tools:
+
+- **Weekly** - your routine sheet with activity layers. Print it or set it as a desktop wallpaper.
+- **Year** - a wide year-at-a-glance planner, with layers fed by your own calendars, public holidays, and manually
+  added events. Print it or set it as a desktop wallpaper.
+
+![Weekly routine sheet](docs/images/weekly.png)
+
+![Year-at-a-glance planner](docs/images/year.png)
+
+## Quick start (Docker)
+
+```sh
+docker compose run --rm timeglance timeglance-init   # first run: scaffold year/ + weekly/ config.yaml
+docker compose up                                    # then open http://localhost:8753
+```
+
+Config, outputs and scheduler state are bind-mounted under `./year`, `./weekly` and `./state`, so the UI edits
+files on your host. Outputs are written as your host user — the compose file defaults to `1000:1000` (the usual
+first Linux user), so it just works for most; if your uid differs, run `UID=$(id -u) GID=$(id -g) docker compose up`.
+
+> Wallpaper-setting needs a live Plasma session, so it works only with the **local install** (next section), not in
+> Docker; the container UI auto-hides it.
+
+## Quick start (local)
+
+Needs Python 3.13 and [uv](https://docs.astral.sh/uv/). WeasyPrint and CairoSVG load native libraries (Cairo, Pango,
+GDK-PixBuf) at runtime; most Linux desktops already have these, but on a minimal or server install add them first
+(Debian/Ubuntu):
+
+```sh
+sudo apt-get install libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0
+uv sync
+uv run timeglance-init     # scaffold year/ + weekly/ config.yaml from the templates
+uv run timeglance          # the control panel at http://localhost:8753
+```
+
+Headless renders (each flag has a YAML equivalent):
+
+```sh
+uv run timeglance-year --theme light --layout vertical   # -> year/out/
+uv run timeglance-weekly --format both                   # -> weekly/out/
+```
+
+## Docs
+
+- [Motivation](docs/motivation.md) - why this exists, and how it fits a GTD/calendar setup
+- [The control panel](docs/control-panel.md) - preview, config editor, scheduler & activity log
+- [Configuration](docs/configuration.md) - year & weekly YAML, calendar (`.ics`) sources
+- [Reference](docs/reference.md) - every CLI flag and YAML key
+- [Wallpaper](docs/wallpaper.md) - KDE Plasma, per-screen native-resolution rendering
+- [Use as a library](docs/library.md) - import and render PNG/PDF/SVG from Python
+- [Contributing](CONTRIBUTING.md) - setup, CI, releasing
+
+## Limitations
+
+- **Wallpaper-setting is host-only.** The container can't reach a Plasma session, so inside Docker the feature
+  self-hides and a scheduled "set wallpaper" renders the files but skips the set (logged as
+  `wallpaper skipped (no backend)`). Run the server/CLI on the host to set wallpapers.
+- **Weekly blocks can't overlap in time.** Two activities over the same slot on the same day render on top of each
+  other, so only one reads clearly.

timeglance-1.0.0/README.md

@@ -0,0 +1,80 @@
+# timeglance
+
+[![Python](https://img.shields.io/python/required-version-toml?color=blue&tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fdannyadair%2Ftimeglance%2Fmain%2Fpyproject.toml)](https://github.com/dannyadair/timeglance/blob/main/pyproject.toml)
+[![tests](https://github.com/dannyadair/timeglance/actions/workflows/tests.yaml/badge.svg)](https://github.com/dannyadair/timeglance/actions/workflows/tests.yaml)
+[![pre-commit](https://img.shields.io/github/actions/workflow/status/dannyadair/timeglance/pre-commit.yaml?label=pre-commit&logo=pre-commit&logoColor=white)](https://github.com/dannyadair/timeglance/actions/workflows/pre-commit.yaml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![pip-audit](https://img.shields.io/github/actions/workflow/status/dannyadair/timeglance/pip-audit.yaml?label=pip-audit&logo=python)](https://github.com/dannyadair/timeglance/actions/workflows/pip-audit.yaml)
+[![bandit](https://img.shields.io/github/actions/workflow/status/dannyadair/timeglance/bandit.yaml?label=bandit&logo=python)](https://github.com/dannyadair/timeglance/actions/workflows/bandit.yaml)
+[![Last commit](https://img.shields.io/github/last-commit/dannyadair/timeglance?color=lightgrey)](https://github.com/dannyadair/timeglance/commits/main)
+[![License](https://img.shields.io/github/license/dannyadair/timeglance?color=lightgrey)](https://github.com/dannyadair/timeglance/blob/main/LICENSE)
+
+<!-- Add once published to PyPI (and if you wire up these services), matching pdfbaker:
+[![PyPI version](https://img.shields.io/pypi/v/timeglance?color=blue)](https://pypi.org/project/timeglance/)
+[![Downloads](https://img.shields.io/pypi/dw/timeglance?color=blue)](https://pypistats.org/packages/timeglance)
+[![sigstore](https://img.shields.io/badge/sigstore-signed-blue)](https://github.com/dannyadair/timeglance/releases)
+[![codecov](https://img.shields.io/codecov/c/github/dannyadair/timeglance)](https://codecov.io/gh/dannyadair/timeglance)
+[![OSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/dannyadair/timeglance?label=OSSF%20Scorecard)](https://scorecard.dev/viewer/?uri=github.com/dannyadair/timeglance)
+-->
+
+Config-driven time planning at a glance - one web UI controls two tools:
+
+- **Weekly** - your routine sheet with activity layers. Print it or set it as a desktop wallpaper.
+- **Year** - a wide year-at-a-glance planner, with layers fed by your own calendars, public holidays, and manually
+  added events. Print it or set it as a desktop wallpaper.
+
+![Weekly routine sheet](docs/images/weekly.png)
+
+![Year-at-a-glance planner](docs/images/year.png)
+
+## Quick start (Docker)
+
+```sh
+docker compose run --rm timeglance timeglance-init   # first run: scaffold year/ + weekly/ config.yaml
+docker compose up                                    # then open http://localhost:8753
+```
+
+Config, outputs and scheduler state are bind-mounted under `./year`, `./weekly` and `./state`, so the UI edits
+files on your host. Outputs are written as your host user — the compose file defaults to `1000:1000` (the usual
+first Linux user), so it just works for most; if your uid differs, run `UID=$(id -u) GID=$(id -g) docker compose up`.
+
+> Wallpaper-setting needs a live Plasma session, so it works only with the **local install** (next section), not in
+> Docker; the container UI auto-hides it.
+
+## Quick start (local)
+
+Needs Python 3.13 and [uv](https://docs.astral.sh/uv/). WeasyPrint and CairoSVG load native libraries (Cairo, Pango,
+GDK-PixBuf) at runtime; most Linux desktops already have these, but on a minimal or server install add them first
+(Debian/Ubuntu):
+
+```sh
+sudo apt-get install libcairo2 libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf-2.0-0
+uv sync
+uv run timeglance-init     # scaffold year/ + weekly/ config.yaml from the templates
+uv run timeglance          # the control panel at http://localhost:8753
+```
+
+Headless renders (each flag has a YAML equivalent):
+
+```sh
+uv run timeglance-year --theme light --layout vertical   # -> year/out/
+uv run timeglance-weekly --format both                   # -> weekly/out/
+```
+
+## Docs
+
+- [Motivation](docs/motivation.md) - why this exists, and how it fits a GTD/calendar setup
+- [The control panel](docs/control-panel.md) - preview, config editor, scheduler & activity log
+- [Configuration](docs/configuration.md) - year & weekly YAML, calendar (`.ics`) sources
+- [Reference](docs/reference.md) - every CLI flag and YAML key
+- [Wallpaper](docs/wallpaper.md) - KDE Plasma, per-screen native-resolution rendering
+- [Use as a library](docs/library.md) - import and render PNG/PDF/SVG from Python
+- [Contributing](CONTRIBUTING.md) - setup, CI, releasing
+
+## Limitations
+
+- **Wallpaper-setting is host-only.** The container can't reach a Plasma session, so inside Docker the feature
+  self-hides and a scheduled "set wallpaper" renders the files but skips the set (logged as
+  `wallpaper skipped (no backend)`). Run the server/CLI on the host to set wallpapers.
+- **Weekly blocks can't overlap in time.** Two activities over the same slot on the same day render on top of each
+  other, so only one reads clearly.

timeglance-1.0.0/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues privately via GitHub's
+[private vulnerability reporting](https://github.com/dannyadair/timeglance/security/advisories/new)
+rather than opening a public issue.
+
+## Scope
+
+timeglance renders local YAML/ICS config to SVG/PDF/PNG and, on KDE Plasma, sets the desktop
+wallpaper via `kscreen-doctor`/`dbus-send`. It fetches the `.ics` URLs you configure and starts a
+control-panel server bound to localhost (`0.0.0.0` only inside the container you run). It exposes no
+other network service.

timeglance-1.0.0/compose.yaml

@@ -0,0 +1,29 @@
+# The whole app is one service: the timeglance control panel.
+#
+#   docker compose run --rm timeglance timeglance-init   # first time: scaffold the configs
+#   docker compose up                                    # open http://localhost:8753
+#
+# Config and output are bind-mounted, so the UI (and the scheduler) edit files on your
+# host and results appear in ./*/out. One-shot CLI renders still work, e.g.
+#   docker compose run --rm timeglance timeglance-year
+#   docker compose run --rm timeglance timeglance-weekly --format both
+#
+# Wallpaper-setting is host-only (needs a Plasma session); it is auto-hidden in the UI here.
+
+# Output and state are written as your host user (defaults to 1000:1000); override with
+#   UID=$(id -u) GID=$(id -g) docker compose up
+x-user: &user "${UID:-1000}:${GID:-1000}"
+
+services:
+  timeglance:
+    build: .
+    command: timeglance --host 0.0.0.0
+    user: *user
+    environment:
+      XDG_CACHE_HOME: /tmp # writable fontconfig cache when running as a non-root uid
+    ports:
+      - "8753:8753"
+    volumes:
+      - ./year:/app/year
+      - ./weekly:/app/weekly
+      - ./state:/app/state

timeglance-1.0.0/docs/configuration.md

@@ -0,0 +1,46 @@
+# Configuration
+
+Working configs (`year/config.yaml`, `weekly/config.yaml`) are git-ignored (personal schedule / calendar
+secrets); the packaged `config.yaml.in` files are annotated templates. Run `timeglance-init` to scaffold the
+working configs from them. Precedence is **built-in defaults < YAML < CLI flags**, so you can comment defaults out
+rather than delete them.
+
+See the [Reference](reference.md) for the full list of flags and YAML keys.
+
+## Year (`year/config.yaml`)
+
+- **`range`** - `start`/`end` accept `today`, `today±N` (months), `year-start`, `year-end`, or `YYYY-MM`.
+  A shorter range renders larger. Or set a `span` preset instead of `start`/`end`: `this_year`,
+  `upcoming_year` (rolling 12 from this month), or `custom` with `before`/`after` month counts.
+- **`holidays`** - auto-populated via the [`holidays`](https://pypi.org/project/holidays/) package
+  (`country` + `subdiv`, e.g. `NZ` / `WGN`).
+- **`sources`** - external iCalendar feeds (see below).
+- **`layers`** / **`events`** - a single day uses `date:`, a span uses `start:`+`end:` (inclusive); recurrence via
+  `repeat: yearly|weekly|monthly` or a full `rrule:` (RFC 5545 / dateutil).
+
+### Calendar sources (.ics)
+
+Let your existing calendars _be_ the editor. Any number of `.ics` feeds are merged into the event stream and mapped
+to a layer:
+
+```yaml
+sources:
+  - url: "https://calendar.proton.me/api/calendar/v1/url/…/calendar.ics" # a Proton share link
+    layer: birthdays
+  - path: "~/calendars/my-year.ics" # a local file
+    label: My Year # creates a layer if `layer:` is omitted
+    color: "#7A7F87"
+```
+
+Recurrences, `EXDATE`s and all-day/timed spans are expanded within the render window. URL feeds are TTL-cached
+(`refresh:` seconds) under `state/ics-cache`, and a failed refresh falls back to the last good copy. Nice trick:
+keep a private "year" calendar you never show online and only export here.
+
+> **A share link is a secret.** Proton links embed a passphrase key. Keep them in your git-ignored `config.yaml`,
+> never in the tracked `config.yaml.in`.
+
+## Weekly (`weekly/config.yaml`)
+
+`activities` (label + colour; `visible: false` hides one by default) and a flat list of `blocks`. Toggle any
+activity in the UI (or with `--hide`/`--only`); comment out a single block to drop a one-off. `wallpaper:` tunes
+the canvas `background`, `margin`, `shadow`, and `screens`.

timeglance-1.0.0/docs/control-panel.md

@@ -0,0 +1,20 @@
+# The control panel
+
+Open <http://localhost:8753>. Switch **Weekly / Year**, and within each, switch the view:
+
+- **Preview** - live render with quick controls (year: theme, layout, week start, range, size, layer toggles;
+  weekly: paper, activity toggles). **Export** (PNG / PDF) and **Set as wallpaper** act on the current controls.
+- **Config** - the tool's full YAML in an editor. **Save** validates and writes it; **Reset to template** restores
+  the annotated template. This is the source of truth - anything not in the quick controls lives here.
+
+Two shared, app-wide views sit alongside them:
+
+- **Schedule** - a daily re-render loop: pick a time and which tools to refresh (optionally setting the wallpaper),
+  **Start / Stop / Run now**. With more than one screen you can assign each tool to specific outputs (e.g. weekly on
+  the laptop, year on the ultrawide); leave all ticked to target every screen. Runs are isolated so one failing feed
+  can't sink the rest.
+- **Log** - a persistent activity log of every render, export and wallpaper change, scheduled or manual (live
+  previews aren't logged). **Clear log** wipes it (with confirmation). Schedule config and the log persist under
+  `state/`.
+
+The YAML is re-read on every request, so external edits show up on reload.